claude-dev-env 7.3.0 → 7.4.1

package/hooks/blocking/test_pii_scanner.py

@@ -55,17 +55,13 @@ def test_allows_hygiene_placeholder_username_example() -> None:
 
 
 def test_flags_unix_home_path() -> None:
-    all_unix_hits = scan_text_for_pii(
-        "config lives in /Users/fixture_real_user/.config"
-    )
+    all_unix_hits = scan_text_for_pii("config lives in /Users/fixture_real_user/.config")
     assert any(each.category == "home-path" for each in all_unix_hits)
 
 
 def test_flags_raw_escaped_windows_home_path() -> None:
     all_home_hits = scan_text_for_pii(r"path is C:\\Users\\concrete-user\\file")
-    assert [each.matched_text for each in all_home_hits] == [
-        r"C:\\Users\\concrete-user"
-    ]
+    assert [each.matched_text for each in all_home_hits] == [r"C:\\Users\\concrete-user"]
 
 
 def test_flags_unc_windows_home_path_at_each_share_depth() -> None:
@@ -82,9 +78,7 @@ def test_flags_unc_windows_home_path_at_each_share_depth() -> None:
 
 def test_flags_forward_slash_unc_home_paths() -> None:
     all_home_hits = scan_text_for_pii(
-        "path is //server/Users/concrete-user/file"
-        "\n"
-        "path is //server/share/Users/other-user/file"
+        "path is //server/Users/concrete-user/file\npath is //server/share/Users/other-user/file"
     )
     assert [each.matched_text for each in all_home_hits] == [
         "//server/Users/concrete-user",
@@ -112,9 +106,7 @@ def test_flags_absolute_and_file_uri_home_paths() -> None:
     all_home_hits += scan_text_for_pii("path is file:///home/concrete-user/file")
     all_home_hits += scan_text_for_pii("path is file://server/home/concrete-user/file")
     all_home_hits += scan_text_for_pii("path is FILE://server/home/other-user/file")
-    all_home_hits += scan_text_for_pii(
-        "path is FILE://server/share/home/third-user/file"
-    )
+    all_home_hits += scan_text_for_pii("path is FILE://server/share/home/third-user/file")
     assert [each.matched_text for each in all_home_hits] == [
         "/home/concrete-user",
         "file:///home/concrete-user",
@@ -191,9 +183,7 @@ def test_flags_github_token_aws_key_and_pem_header() -> None:
 def test_secret_and_email_previews_are_redacted() -> None:
     all_secret_hits = scan_text_for_pii(f"export TOKEN={SYNTHETIC_GITHUB_TOKEN}")
     all_email_hits = scan_text_for_pii(f"contact {SYNTHETIC_REAL_EMAIL}")
-    secret_finding = next(
-        each for each in all_secret_hits if each.category == "secret"
-    )
+    secret_finding = next(each for each in all_secret_hits if each.category == "secret")
     email_finding = next(each for each in all_email_hits if each.category == "email")
     assert secret_finding.matched_text == SYNTHETIC_GITHUB_TOKEN
     assert SYNTHETIC_GITHUB_TOKEN not in secret_finding.preview
@@ -217,9 +207,7 @@ def test_flags_genuine_human_home_username() -> None:
 
 def test_short_nonsafe_email_preview_is_fully_redacted() -> None:
     all_email_hits = scan_text_for_pii("reach owner@acme.io")
-    email_finding = next(
-        each for each in all_email_hits if each.category == "email"
-    )
+    email_finding = next(each for each in all_email_hits if each.category == "email")
     assert email_finding.matched_text == "owner@acme.io"
     assert email_finding.preview == "[redacted]"
     assert "owner" not in email_finding.preview
@@ -227,9 +215,7 @@ def test_short_nonsafe_email_preview_is_fully_redacted() -> None:
 
 def test_home_path_preview_redacts_only_the_username() -> None:
     all_home_hits = scan_text_for_pii(r"path is C:\Users\johnsmith\secret.txt")
-    home_finding = next(
-        each for each in all_home_hits if each.category == "home-path"
-    )
+    home_finding = next(each for each in all_home_hits if each.category == "home-path")
     assert "johnsmith" not in home_finding.preview
     assert "[redacted]" in home_finding.preview
     assert "Users" in home_finding.preview
@@ -237,9 +223,7 @@ def test_home_path_preview_redacts_only_the_username() -> None:
 
 def test_home_path_preview_redacts_home_segment_when_name_repeats_earlier() -> None:
     all_home_hits = scan_text_for_pii(r"path is C:\Users\Users\secret.txt")
-    home_finding = next(
-        each for each in all_home_hits if each.category == "home-path"
-    )
+    home_finding = next(each for each in all_home_hits if each.category == "home-path")
     assert home_finding.preview == r"C:\Users\[redacted]"
 
 
@@ -269,3 +253,29 @@ def test_path_exemptions_for_tests_license_and_self_modules() -> None:
 def test_empty_path_still_scans_payload_text() -> None:
     all_hits = scan_text_for_pii(f"contact {SYNTHETIC_REAL_EMAIL}")
     assert any(each.category == "email" for each in all_hits)
+
+
+def test_home_match_stops_at_source_string_boundary() -> None:
+    findings = scan_text_for_pii('path = "C:/Users/concrete-user"\nnext_path = "C:/data"')
+    assert [(item.category, item.matched_text) for item in findings] == [
+        ("home-path", "C:/Users/concrete-user")
+    ]
+
+
+def test_allows_interpolated_home_username() -> None:
+    assert scan_text_for_pii('path = f"C:/Users/{username}/Documents"') == []
+    assert scan_text_for_pii('path = f"C:/Users/{username}"\nnext_path = "C:/data"') == []
+
+
+def test_template_username_does_not_exempt_literal_username() -> None:
+    findings = scan_text_for_pii('path = "C:/Users/concrete-user{suffix}/Documents"')
+    assert [item.category for item in findings] == ["home-path"]
+
+
+def test_preserves_apostrophes_and_parentheses_in_usernames() -> None:
+    findings = scan_text_for_pii("C:/Users/O'Neil/Documents\nC:/Users/Jane (Work)/Documents")
+    assert [item.matched_text for item in findings] == ["C:/Users/O'Neil", "C:/Users/Jane (Work)"]
+
+
+def test_escaped_placeholder_username_uses_complete_separator() -> None:
+    assert scan_text_for_pii(r"C:\\Users\\example\\Documents") == []

package/hooks/hooks_constants/env_var_table_code_drift_constants.py

@@ -16,6 +16,9 @@ __all__ = [
     "SEPARATOR_CELL_PATTERN",
     "BACKTICK_TOKEN_PATTERN",
     "ENV_VAR_NAME_PATTERN",
+    "ENV_VAR_HEADER_PATTERN",
+    "ALL_GENERIC_ENV_VAR_HEADERS",
+    "ENV_VAR_HEADING_PATTERN",
     "ALL_CODE_FILE_EXTENSIONS",
     "ALL_NOISE_DIRECTORY_NAMES",
     "GIT_DIRECTORY_NAME",
@@ -34,10 +37,13 @@ CODE_FENCE_PATTERN = re.compile(r"^\s*(```|~~~)")
 SEPARATOR_CELL_PATTERN = re.compile(r"^[:\-\s]+$")
 BACKTICK_TOKEN_PATTERN = re.compile(r"`([^`]+)`")
 ENV_VAR_NAME_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]{1,}$")
-
-ALL_CODE_FILE_EXTENSIONS: frozenset[str] = frozenset(
-    {".py", ".mjs", ".js", ".ts", ".ps1", ".sh"}
+ENV_VAR_HEADER_PATTERN = re.compile(
+    r"^(?:(?:environment|env)[ -]+)?(?:variables?|vars?)(?:[ -]+(?:name|key))?$", re.I
 )
+ALL_GENERIC_ENV_VAR_HEADERS = frozenset({"name", "key"})
+ENV_VAR_HEADING_PATTERN = re.compile(r"\b(?:environment|env)[ -]+(?:variables?|vars?)\b", re.I)
+
+ALL_CODE_FILE_EXTENSIONS: frozenset[str] = frozenset({".py", ".mjs", ".js", ".ts", ".ps1", ".sh"})
 ALL_NOISE_DIRECTORY_NAMES: frozenset[str] = frozenset(
     {".git", "__pycache__", "node_modules", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
 )
@@ -61,4 +67,6 @@ DRIFT_ADDITIONAL_CONTEXT = (
     "its source never references the variable name, the row is stale. Drop the "
     "row, or point it at the variable the file actually reads."
 )
-DRIFT_SYSTEM_MESSAGE = "Blocked: env-var summary table attributes a variable to a code file that does not read it."
+DRIFT_SYSTEM_MESSAGE = (
+    "Blocked: env-var summary table attributes a variable to a code file that does not read it."
+)

package/hooks/hooks_constants/hardcoded_user_path_constants.py

@@ -4,15 +4,17 @@ import re
 
 HARDCODED_USER_PATH_PATTERN: re.Pattern[str] = re.compile(
     r"(?:"
-    r"[A-Za-z]:[\\/]+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
-    r"|\\{2,}(?:[^\\/\r\n]+[\\/]+)+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
-    r"|(?<!:)//(?:[^\\/\r\n]+/)+(?i:users)/(?!(?i:Public|Shared|All Users)(?:/|$))[^/]+(?=/|$)"
-    r"|(?i:file):///Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:Users)/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|(?i:file):///home/[^/]+(?=/|$)"
-    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:home)/[^/]+(?=/|$)"
-    r"|(?<![A-Za-z0-9._:/\-\]])/Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|(?<![A-Za-z0-9._:/\-\]])/home/[^/]+(?=/|$))"
+    r"[A-Za-z]:[\\/]+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))(?:[^\\/\r\n\"`]+(?=[\\/])|[^\\/\r\n\"'`()]+(?=[\\/\r\n\"'`()]|$))"
+    r"|\\{2,}(?:[^\\/\r\n]+[\\/]+)+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))(?:[^\\/\r\n\"`]+(?=[\\/])|[^\\/\r\n\"'`()]+(?=[\\/\r\n\"'`()]|$))"
+    r"|(?<!:)//(?:[^\\/\r\n]+/)+(?i:users)/(?!(?i:Public|Shared|All Users)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file):///Users/(?!(?i:Shared|Public)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:Users)/(?!(?i:Shared|Public)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file):///home/(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:home)/(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?<![A-Za-z0-9._:/\-\]])/Users/(?!(?i:Shared|Public)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?<![A-Za-z0-9._:/\-\]])/home/(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$)))"
 )
 MAX_HARDCODED_USER_PATH_ISSUES: int = 25
-HARDCODED_USER_PATH_GUIDANCE: str = "use pathlib.Path.home() or os.path.expanduser('~') instead of a hardcoded user directory"
+HARDCODED_USER_PATH_GUIDANCE: str = (
+    "use pathlib.Path.home() or os.path.expanduser('~') instead of a hardcoded user directory"
+)

package/hooks/hooks_constants/pii_prevention_constants.py

@@ -18,9 +18,7 @@ from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: F401
 BASH_TOOL_NAME: str = "Bash"
 POWERSHELL_TOOL_NAME: str = "PowerShell"
 
-ALL_SHELL_TOOL_NAMES: frozenset[str] = frozenset(
-    {BASH_TOOL_NAME, POWERSHELL_TOOL_NAME}
-)
+ALL_SHELL_TOOL_NAMES: frozenset[str] = frozenset({BASH_TOOL_NAME, POWERSHELL_TOOL_NAME})
 
 ALL_GIT_BINARY_BASENAMES: frozenset[str] = frozenset({"git", "git.exe"})
 GIT_COMMIT_SUBCOMMAND: str = "commit"
@@ -29,12 +27,8 @@ ALL_VALUE_TAKING_GIT_OPTIONS: frozenset[str] = frozenset(
     {GIT_WORKING_DIRECTORY_OPTION, "-c", "--git-dir", "--work-tree", "--namespace"}
 )
 GIT_OPTION_WITH_VALUE_STEP: int = 2
-ALL_SHELL_COMMAND_SEPARATOR_TOKENS: frozenset[str] = frozenset(
-    {"&&", "||", ";", "|", "&"}
-)
-ALL_SHELL_KEYWORD_TOKENS: frozenset[str] = frozenset(
-    {"then", "do", "else", "elif"}
-)
+ALL_SHELL_COMMAND_SEPARATOR_TOKENS: frozenset[str] = frozenset({"&&", "||", ";", "|", "&"})
+ALL_SHELL_KEYWORD_TOKENS: frozenset[str] = frozenset({"then", "do", "else", "elif"})
 ALL_COMMAND_WRAPPER_TOKENS: frozenset[str] = frozenset(
     {
         "sudo",
@@ -85,9 +79,7 @@ SINGLE_DASH_OPTION_PREFIX: str = "-"
 DOUBLE_DASH_OPTION_PREFIX: str = "--"
 ALL_SHELL_QUOTE_CHARACTERS: frozenset[str] = frozenset({'"', "'"})
 ALL_COMMAND_BOUNDARY_NEWLINE_CHARACTERS: frozenset[str] = frozenset({"\n", "\r"})
-ENVIRONMENT_ASSIGNMENT_PATTERN: re.Pattern[str] = re.compile(
-    r"^[A-Za-z_][A-Za-z0-9_]*="
-)
+ENVIRONMENT_ASSIGNMENT_PATTERN: re.Pattern[str] = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
 LINE_CONTINUATION_PATTERN: re.Pattern[str] = re.compile(r"\\\r?\n")
 POWERSHELL_LINE_CONTINUATION_PATTERN: re.Pattern[str] = re.compile(r"`\r?\n")
 
@@ -223,9 +215,7 @@ CATEGORY_HOME_PATH: str = "home-path"
 CATEGORY_PRIVATE_IP: str = "private-ip"
 CATEGORY_SECRET: str = "secret"
 
-ALL_REDACTED_PREVIEW_CATEGORIES: frozenset[str] = frozenset(
-    {CATEGORY_EMAIL, CATEGORY_SECRET}
-)
+ALL_REDACTED_PREVIEW_CATEGORIES: frozenset[str] = frozenset({CATEGORY_EMAIL, CATEGORY_SECRET})
 REDACTED_PREVIEW_PREFIX_LENGTH: int = 4
 REDACTED_PREVIEW_SUFFIX_LENGTH: int = 4
 REDACTED_PREVIEW_REVEALED_LENGTH: int = (
@@ -238,9 +228,7 @@ MINIMUM_LENGTH_FOR_PARTIAL_REDACTION: int = (
     REDACTED_PREVIEW_REVEALED_LENGTH + REDACTED_PREVIEW_MINIMUM_HIDDEN_LENGTH
 )
 
-EMAIL_PATTERN: re.Pattern[str] = re.compile(
-    r"(?i)\b([A-Z0-9._%+\-]+@[A-Z0-9.\-]+\.[A-Z]{2,})\b"
-)
+EMAIL_PATTERN: re.Pattern[str] = re.compile(r"(?i)\b([A-Z0-9._%+\-]+@[A-Z0-9.\-]+\.[A-Z]{2,})\b")
 
 IPV4_PATTERN: re.Pattern[str] = re.compile(
     r"\b((?:25[0-5]|2[0-4]\d|1?\d?\d)\."
@@ -249,13 +237,9 @@ IPV4_PATTERN: re.Pattern[str] = re.compile(
     r"(?:25[0-5]|2[0-4]\d|1?\d?\d))\b"
 )
 
-GITHUB_TOKEN_PATTERN: re.Pattern[str] = re.compile(
-    r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b"
-)
+GITHUB_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b")
 
-GITHUB_FINE_GRAINED_TOKEN_PATTERN: re.Pattern[str] = re.compile(
-    r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"
-)
+GITHUB_FINE_GRAINED_TOKEN_PATTERN: re.Pattern[str] = re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b")
 
 AWS_ACCESS_KEY_PATTERN: re.Pattern[str] = re.compile(r"\bAKIA[0-9A-Z]{16}\b")
 
@@ -264,8 +248,9 @@ PEM_PRIVATE_KEY_HEADER_PATTERN: re.Pattern[str] = re.compile(
 )
 
 HOME_PATH_PATTERN: re.Pattern[str] = HARDCODED_USER_PATH_PATTERN
+INTERPOLATED_HOME_USERNAME_PATTERN: re.Pattern[str] = re.compile(r"^\{[A-Za-z_][A-Za-z0-9_]*\}$")
 
-ALL_HOME_DIRECTORY_PATH_MARKERS: tuple[str, ...] = ("/users/", "/home/")
+HOME_USERNAME_MARKER_PATTERN: re.Pattern[str] = re.compile(r"[\\/]+(?:users|home)[\\/]+", re.I)
 
 ALL_SECRET_PATTERNS: tuple[re.Pattern[str], ...] = (
     GITHUB_TOKEN_PATTERN,

package/package.json

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

package/scripts/pstack-adapters/common.md

@@ -4,7 +4,7 @@ Apply this mapping to the upstream workflow below. User instructions and host pe
 
 Determine the active host from the session's native tools. Read host-claude.md, host-codex.md, or host-cursor.md beside this file for the active host. Read pstack-host-mapping.md and pstack-models.md beside this file before delegation. Those files are copied from claude-dev-env's existing rules into this immutable release. Run the selectorPath recorded in release.json and supply its preferencesDirectory in the selector input. This overrides the old global selector path. Model preferences remain outside the release.
 
-Installed skill names have a component prefix. Read the installed inventory in release.json. A pstack request for how, /how, or pstack:how means pstack-how. A cursor-team-kit request for deslop means cursor-team-kit-deslop. Resolve all other skill names through that inventory. Read each leaf skill in full when it applies. Keep each skill's scripts, references, playbooks, and agent definitions at its recorded source root.
+Read the installed inventory in release.json for exact skill identities. Pstack skills use the `pstack:<slug>` plugin namespace. A pstack request for how, /how, or pstack:how means pstack:how. Cursor-team-kit skills keep flat component-prefixed names, so a request for deslop means cursor-team-kit-deslop. Resolve all other skill names through the inventory. Read each leaf skill in full when it applies. Keep each skill's scripts, references, playbooks, and agent definitions at its recorded source root.
 
 Every delegation prompt must include this compatibility file's absolute path, the active host file's absolute path, the selected skill's absolute path, and the requested upstream agent definition's absolute path when present. Tell the child to read them before working and to put the complete findings and evidence in its final message. The child receives the same host and model mapping as the parent.
 

package/scripts/repository_checks/config/constants.py

@@ -99,37 +99,27 @@ ALL_TRACKED_SECRET_EXACT_EXEMPTIONS: frozenset[tuple[str, str, str]] = frozenset
         (
             "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
             "home-path",
-            "9c48917645524d03ea0a4f4d8755aa8f0d59f3108e1aa976202a02e613c1444d",
-        ),
-        (
-            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
-            "home-path",
-            "07ba214cb23325675bc68e5513c030e968eccf2760cb5917d932ae5da29d5af1",
-        ),
-        (
-            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
-            "home-path",
-            "d41ce8d0f21de2d5320bdd8cd4e8693a2f3d6ea59db6df5ea102a7d2be4b2c22",
+            "f9e409c5c16ecfdd5883da4f3ad045b4af5677740c9e703ad2d47ba231718350",
         ),
         (
             "packages/claude-dev-env/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md",
             "home-path",
-            "550c7b16a2a04e1d05a8a6b4f5b764b8d4fdef65e9d79d09e5dbb3a15a855812",
+            "6b98ff7f0398f06452f19c4a93f3d69186401dab40aaa7077b394ef59b3e730e",
         ),
         (
-            "packages/claude-dev-env/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md",
+            "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
             "home-path",
-            "b8bbdd1a7ebdad16f4e51377a3f21d05dd35992d89e35971b28b05f53245c69d",
+            "31e989aa0fbf83d6de5d2f0cd6f08b3cd8151592050b71794ffa180b80385ff2",
         ),
         (
             "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
             "home-path",
-            "10d5571e7126d2018ee7fb06aa29c72a9d503cac79a4e52d6848602ee10e8832",
+            "73ff793e488241663bb0c075fd50bd3a18fca8dd79cbd11629c00d2ad7548a8a",
         ),
         (
             "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
             "home-path",
-            "09f83c224a02c370d3d63de5c330e1a830fc92866330fc7963b5b5fd20ffcb91",
+            "fd9ba4ae930ef31ebdfc463b231a093656b8eaa1d8fe65f60715ec2b6fee04a9",
         ),
         (
             "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
@@ -139,7 +129,7 @@ ALL_TRACKED_SECRET_EXACT_EXEMPTIONS: frozenset[tuple[str, str, str]] = frozenset
         (
             "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
             "home-path",
-            "a541acfac2e649581bca0cd03e4c3dcf306344915017d9cd6be4ad57a8fd7379",
+            "5d956228802fbd4a65af8fa7fb4183f5a9f8793dbe218877aefe887b905f726d",
         ),
     )
 )

package/scripts/repository_checks/config/email_exemptions.py

@@ -0,0 +1,10 @@
+"""Repository public-email exception schema."""
+
+import re
+
+CONFIG_RELATIVE_PATH = "config/repository-policy.json"
+DIGEST_PATTERN = re.compile(r"[0-9a-f]{64}")
+FORBIDDEN_PATH_CHARACTERS = frozenset("\\:*?[]")
+ALL_ENTRY_FIELDS = frozenset({"path", "sha256", "reason"})
+ALL_FORBIDDEN_PATH_SEGMENTS = frozenset({"", ".", ".."})
+FIRST_PRINTABLE_CODEPOINT = 32

package/scripts/repository_checks/email_exemptions.py

@@ -0,0 +1,96 @@
+"""Load exact public-email exceptions owned by a repository."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from repository_checks.config.email_exemptions import (
+    ALL_ENTRY_FIELDS,
+    ALL_FORBIDDEN_PATH_SEGMENTS,
+    CONFIG_RELATIVE_PATH,
+    DIGEST_PATTERN,
+    FIRST_PRINTABLE_CODEPOINT,
+    FORBIDDEN_PATH_CHARACTERS,
+)
+
+
+class PolicyConfigurationRunFatal(ValueError):
+    """Reject the entire policy run when exception configuration is invalid."""
+
+
+def load_email_exemptions(repository_root: Path) -> frozenset[tuple[str, str, str]]:
+    """Read validated email exceptions.
+
+    Args:
+        repository_root: Repository containing the optional policy configuration.
+    Returns:
+        Exact path, email category, and digest identities.
+    Raises:
+        ValueError: Configuration contains invalid JSON or schema fields.
+        OSError: Configuration cannot be read.
+    """
+    exemptions: set[tuple[str, str, str]] = set()
+    for each_entry in _read_entries(repository_root):
+        identity = _entry_identity(each_entry)
+        if identity in exemptions:
+            raise PolicyConfigurationRunFatal("Duplicate repository email exemption")
+        exemptions.add(identity)
+    return frozenset(exemptions)
+
+
+def _read_entries(repository_root: Path) -> list[object]:
+    config_path = repository_root / CONFIG_RELATIVE_PATH
+    if not config_path.exists() and not config_path.is_symlink():
+        return []
+    if not config_path.resolve().is_relative_to(repository_root.resolve()):
+        raise ValueError(
+            "Repository policy configuration must remain inside the repository"
+        )
+    document = json.loads(
+        config_path.read_text(encoding="utf-8"), object_pairs_hook=_unique_fields
+    )
+    if (
+        not isinstance(document, dict)
+        or set(document) != {"version", "email_exemptions"}
+        or type(document["version"]) is not int
+        or document["version"] != 1
+        or not isinstance(document["email_exemptions"], list)
+    ):
+        raise ValueError("Invalid repository policy configuration schema")
+    return document["email_exemptions"]
+
+
+def _unique_fields(all_pairs: list[tuple[str, object]]) -> dict[str, object]:
+    fields: dict[str, object] = {}
+    for each_key, each_content in all_pairs:
+        if each_key in fields:
+            raise PolicyConfigurationRunFatal("Duplicate repository policy field")
+        fields[each_key] = each_content
+    return fields
+
+
+def _entry_identity(entry: object) -> tuple[str, str, str]:
+    if not isinstance(entry, dict) or set(entry) != ALL_ENTRY_FIELDS:
+        raise ValueError("Email exemptions require path, sha256, and reason")
+    relative_path, digest, reason = entry["path"], entry["sha256"], entry["reason"]
+    if not isinstance(relative_path, str) or not relative_path:
+        raise ValueError("Email exemption path must name one repository file")
+    if (
+        any(character in FORBIDDEN_PATH_CHARACTERS for character in relative_path)
+        or any(
+            segment in ALL_FORBIDDEN_PATH_SEGMENTS
+            for segment in relative_path.split("/")
+        )
+        or any(
+            ord(character) < FIRST_PRINTABLE_CODEPOINT for character in relative_path
+        )
+    ):
+        raise ValueError("Email exemption path must be a literal relative file path")
+    if not isinstance(digest, str) or DIGEST_PATTERN.fullmatch(digest) is None:
+        raise ValueError("Email exemption sha256 must contain 64 lowercase hex digits")
+    if not isinstance(reason, str) or not reason.strip():
+        raise ValueError(
+            "Email exemption reason must explain its public contact purpose"
+        )
+    return relative_path, "email", digest

package/scripts/repository_checks/env_var_documentation.py

@@ -138,15 +138,7 @@ def _iter_env_var_code_references(
     drift_module: ModuleType,
     drift_constants: ModuleType,
 ) -> Iterator[str]:
-    is_inside_code_fence = False
-    for each_line in content.splitlines():
-        if drift_constants.CODE_FENCE_PATTERN.match(each_line) is not None:
-            is_inside_code_fence = not is_inside_code_fence
-            continue
-        if is_inside_code_fence:
-            continue
-        if drift_constants.TABLE_ROW_PATTERN.match(each_line) is None:
-            continue
+    for each_line in drift_module.iter_env_var_table_rows(content):
         maybe_code_reference = _code_reference_for_env_var_row(
             each_line,
             drift_module,

package/scripts/repository_checks/tracked_secrets.py

@@ -10,6 +10,7 @@ from types import ModuleType
 from policy_lint.config import constants as policy_constants
 
 from repository_checks.config import constants as repository_constants
+from repository_checks.email_exemptions import load_email_exemptions
 from repository_checks.hook_modules import load_hooks_module
 from repository_checks.models import RepositoryFinding
 
@@ -29,6 +30,8 @@ def collect_tracked_secret_findings(
     scanner = load_hooks_module(repository_constants.PII_SCANNER_MODULE_NAME)
     exemption = load_hooks_module(repository_constants.REPOSITORY_EXEMPTION_MODULE_NAME)
     all_allowlisted_literals = exemption.repository_allowlisted_values(repository_root)
+    all_exact_exemptions = load_email_exemptions(repository_root)
+    all_exact_exemptions |= repository_constants.ALL_TRACKED_SECRET_EXACT_EXEMPTIONS
     all_findings: list[RepositoryFinding] = []
     for each_relative_path in all_tracked_paths:
         all_findings.extend(
@@ -37,6 +40,7 @@ def collect_tracked_secret_findings(
                 each_relative_path,
                 scanner,
                 all_allowlisted_literals,
+                all_exact_exemptions,
             )
         )
     return all_findings
@@ -47,6 +51,7 @@ def _find_secrets_for_path(
     relative_path: str,
     scanner: ModuleType,
     all_allowlisted_literals: frozenset[str],
+    all_exact_exemptions: frozenset[tuple[str, str, str]],
 ) -> list[RepositoryFinding]:
     posix_relative_path = relative_path.replace(
         repository_constants.WINDOWS_PATH_SEPARATOR,
@@ -65,6 +70,7 @@ def _find_secrets_for_path(
         maybe_content,
         scanner,
         all_allowlisted_literals,
+        all_exact_exemptions,
     )
 
 
@@ -73,6 +79,7 @@ def _find_secret_matches(
     content: str,
     scanner: ModuleType,
     all_allowlisted_literals: frozenset[str],
+    all_exact_exemptions: frozenset[tuple[str, str, str]],
 ) -> list[RepositoryFinding]:
     return [
         _build_finding(
@@ -86,6 +93,7 @@ def _find_secret_matches(
             each_match.category,
             each_match.matched_text,
             all_allowlisted_literals,
+            all_exact_exemptions,
         )
     ]
 
@@ -127,16 +135,14 @@ def _should_report_match(
     category: str,
     matched_text: str,
     all_allowlisted_literals: frozenset[str],
+    all_exact_exemptions: frozenset[tuple[str, str, str]],
 ) -> bool:
     exact_exemption_identity = (
         posix_relative_path,
         category,
         _secret_digest(matched_text),
     )
-    if (
-        exact_exemption_identity
-        in repository_constants.ALL_TRACKED_SECRET_EXACT_EXEMPTIONS
-    ):
+    if exact_exemption_identity in all_exact_exemptions:
         return False
     return matched_text not in all_allowlisted_literals
 

package/scripts/tests/test_email_exemptions.py

@@ -0,0 +1,121 @@
+"""Exact public-contact exceptions preserve all other scanner findings."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+import pytest
+from repository_checks.email_exemptions import load_email_exemptions
+from repository_checks.tracked_secrets import collect_tracked_secret_findings
+
+CONTACT = "fixture-contact@company.io"
+CHANGED_CONTACT = "changed-contact@company.io"
+DIGEST = hashlib.sha256(CONTACT.encode()).hexdigest()
+
+
+def _write_config(root: Path, entries: list[object]) -> None:
+    directory = root / "config"
+    directory.mkdir(exist_ok=True)
+    (directory / "repository-policy.json").write_text(
+        json.dumps({"version": 1, "email_exemptions": entries}), encoding="utf-8"
+    )
+
+
+def _entry(**changes: object) -> dict[str, object]:
+    return {
+        "path": "contacts.py",
+        "sha256": DIGEST,
+        "reason": "Published support contact",
+        **changes,
+    }
+
+
+def test_only_matching_email_and_path_are_exempt(tmp_path: Path) -> None:
+    _write_config(tmp_path, [_entry()])
+    (tmp_path / "contacts.py").write_text(
+        f"contact = '{CONTACT}'\nchanged = '{CHANGED_CONTACT}'\n", encoding="utf-8"
+    )
+    (tmp_path / "other.py").write_text(f"contact = '{CONTACT}'\n", encoding="utf-8")
+    findings = collect_tracked_secret_findings(tmp_path, ["contacts.py", "other.py"])
+    assert [finding.relative_path for finding in findings] == [
+        "contacts.py",
+        "other.py",
+    ]
+    assert all(finding.message.startswith("[email]") for finding in findings)
+
+
+def test_matching_contact_has_no_findings(tmp_path: Path) -> None:
+    _write_config(tmp_path, [_entry()])
+    (tmp_path / "contacts.py").write_text(f"contact = '{CONTACT}'\n", encoding="utf-8")
+    assert collect_tracked_secret_findings(tmp_path, ["contacts.py"]) == []
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/contacts.py",
+        "C:/contacts.py",
+        "../contacts.py",
+        "src/../contacts.py",
+        "*.py",
+        "src/?.py",
+        "src/[a].py",
+        "src\\contacts.py",
+        "src//contacts.py",
+        "./contacts.py",
+        "",
+    ],
+)
+def test_rejects_nonliteral_or_nonrelative_paths(tmp_path: Path, path: str) -> None:
+    _write_config(tmp_path, [_entry(path=path)])
+    with pytest.raises(ValueError):
+        load_email_exemptions(tmp_path)
+
+
+@pytest.mark.parametrize(
+    "entry",
+    [
+        None,
+        {},
+        _entry(reason=" "),
+        _entry(sha256="f" * 63),
+        _entry(sha256="z" * 64),
+        _entry(category="secret"),
+    ],
+)
+def test_rejects_invalid_entries(tmp_path: Path, entry: object) -> None:
+    _write_config(tmp_path, [entry])
+    with pytest.raises(ValueError):
+        load_email_exemptions(tmp_path)
+
+
+def test_rejects_duplicate_entries(tmp_path: Path) -> None:
+    _write_config(tmp_path, [_entry(), _entry(reason="Another explanation")])
+    with pytest.raises(ValueError):
+        load_email_exemptions(tmp_path)
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        "{",
+        "[]",
+        '{"version":true,"email_exemptions":[]}',
+        '{"version":1,"email_exemptions":{}}',
+        '{"version":1,"email_exemptions":[],"extra":0}',
+        '{"version":1,"version":1,"email_exemptions":[]}',
+    ],
+)
+def test_malformed_config_stops_scanning(tmp_path: Path, content: str) -> None:
+    (tmp_path / "config").mkdir()
+    (tmp_path / "config" / "repository-policy.json").write_text(
+        content, encoding="utf-8"
+    )
+    with pytest.raises(ValueError):
+        collect_tracked_secret_findings(tmp_path, [])
+
+
+def test_missing_config_has_no_exemptions(tmp_path: Path) -> None:
+    assert load_email_exemptions(tmp_path) == frozenset()