claude-dev-env 1.78.0 → 1.80.0

package/hooks/blocking/test_code_rules_js_returns_object_schemaless.py

@@ -0,0 +1,167 @@
+"""Tests for check_js_returns_object_schemaless_branch.
+
+The check catches the JS/.mjs Category O6 docstring-prose-vs-implementation
+drift PR #807 surfaced: a ``function`` whose JSDoc ``@returns {Promise<object>}``
+promises a structured object, while one branch returns the agent-spawn helper
+with an options object that omits ``schema``. A schema-less agent call resolves
+to a transcript string, not the object the JSDoc claims, so the contract drifts
+for that branch while a sibling branch that does pass ``schema`` returns a real
+object.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+
+_module_spec = importlib.util.spec_from_file_location(
+    "code_rules_imports_logging",
+    _HOOK_DIRECTORY / "code_rules_imports_logging.py",
+)
+assert _module_spec is not None
+assert _module_spec.loader is not None
+_imports_logging_module = importlib.util.module_from_spec(_module_spec)
+_module_spec.loader.exec_module(_imports_logging_module)
+
+check_js_returns_object_schemaless_branch = (
+    _imports_logging_module.check_js_returns_object_schemaless_branch
+)
+
+_MJS_PATH = "skills/autoconverge/workflow/converge.mjs"
+
+_SHIPPED_CONVERGE_MJS = (
+    _HOOK_DIRECTORY.parents[1] / "skills" / "autoconverge" / "workflow" / "converge.mjs"
+)
+
+
+def _mixed_schema_source() -> str:
+    return (
+        "/**\n"
+        " * Spawn a git-utility agent for a task.\n"
+        " * @returns {Promise<object>} the structured output\n"
+        " */\n"
+        "function runGitTask(task, head) {\n"
+        "  if (task === 'resolve-head') {\n"
+        "    return convergeAgent(\n"
+        "      `Print the HEAD SHA of ${prCoordinates}.`,\n"
+        "      { label: 'git-utility', phase: 'Converge', schema: HEAD_SCHEMA, agentType: 'Explore' },\n"
+        "    )\n"
+        "  }\n"
+        "  if (task === 'prefetch-main') {\n"
+        "    return convergeAgent(\n"
+        "      `Refresh the base ref for ${prCoordinates}.`,\n"
+        "      { label: 'git-utility', phase: 'Converge', agentType: 'Explore' },\n"
+        "    )\n"
+        "  }\n"
+        "  return convergeAgent(\n"
+        "    `Report conflicts for ${prCoordinates}.`,\n"
+        "    { label: 'git-utility', phase: 'Converge', schema: MERGE_CONFLICT_SCHEMA, agentType: 'Explore' },\n"
+        "  )\n"
+        "}\n"
+    )
+
+
+def _all_schema_source() -> str:
+    return _mixed_schema_source().replace(
+        "      { label: 'git-utility', phase: 'Converge', agentType: 'Explore' },\n",
+        "      { label: 'git-utility', phase: 'Converge', schema: FETCH_SCHEMA, agentType: 'Explore' },\n",
+    )
+
+
+def _plain_object_return_source() -> str:
+    return (
+        "/**\n"
+        " * Joined fixer recovery loop.\n"
+        " * @returns {Promise<object>} FIX_SCHEMA result\n"
+        " */\n"
+        "async function fixerWithRecovery(head, findings, sourceLabel) {\n"
+        "  if (!verdictPassed) {\n"
+        "    return {\n"
+        "      newSha: head,\n"
+        "      pushed: false,\n"
+        "      summary: `verify step did not pass ${sourceLabel}`,\n"
+        "    }\n"
+        "  }\n"
+        "  return commitWithRecovery({\n"
+        "    runCommit: () => runFixerTask('commit', { head }),\n"
+        "    runVerify: () => runVerifierTask('fix-verify', { head }),\n"
+        "  })\n"
+        "}\n"
+    )
+
+
+def _transcript_typed_source() -> str:
+    return _mixed_schema_source().replace(
+        " * @returns {Promise<object>} the structured output\n",
+        " * @returns {Promise<*>} the agent() result\n",
+    )
+
+
+def _destructured_parameter_mixed_schema_source() -> str:
+    return (
+        "/**\n"
+        " * Commit and verify with recovery.\n"
+        " * @returns {Promise<object>} the structured verify output\n"
+        " */\n"
+        "async function commitWithRecovery({ runCommit, runVerify, head }) {\n"
+        "  if (runVerify) {\n"
+        "    return convergeAgent(\n"
+        "      `Verify the commit for ${head}.`,\n"
+        "      { label: 'commit-recovery', phase: 'Converge', schema: VERIFY_SCHEMA, agentType: 'Explore' },\n"
+        "    )\n"
+        "  }\n"
+        "  return convergeAgent(\n"
+        "    `Commit ${head} without verification.`,\n"
+        "    { label: 'commit-recovery', phase: 'Converge', agentType: 'Explore' },\n"
+        "  )\n"
+        "}\n"
+    )
+
+
+def test_flags_schema_less_branch_under_returns_object_claim() -> None:
+    issues = check_js_returns_object_schemaless_branch(_mixed_schema_source(), _MJS_PATH)
+    assert len(issues) == 1
+    assert "runGitTask" in issues[0]
+    assert "convergeAgent" in issues[0]
+
+
+def test_flags_schema_less_branch_with_destructured_parameter() -> None:
+    issues = check_js_returns_object_schemaless_branch(
+        _destructured_parameter_mixed_schema_source(), _MJS_PATH
+    )
+    assert len(issues) == 1
+    assert "commitWithRecovery" in issues[0]
+    assert "convergeAgent" in issues[0]
+
+
+def test_accepts_function_when_every_branch_passes_a_schema() -> None:
+    issues = check_js_returns_object_schemaless_branch(_all_schema_source(), _MJS_PATH)
+    assert issues == []
+
+
+def test_accepts_plain_object_returns_with_no_schema_driven_helper() -> None:
+    issues = check_js_returns_object_schemaless_branch(_plain_object_return_source(), _MJS_PATH)
+    assert issues == []
+
+
+def test_accepts_transcript_typed_returns_clause() -> None:
+    issues = check_js_returns_object_schemaless_branch(_transcript_typed_source(), _MJS_PATH)
+    assert issues == []
+
+
+def test_skips_python_files() -> None:
+    issues = check_js_returns_object_schemaless_branch(
+        _mixed_schema_source(), "workflow/converge.py"
+    )
+    assert issues == []
+
+
+def test_shipped_converge_mjs_passes_its_own_check() -> None:
+    shipped_source = _SHIPPED_CONVERGE_MJS.read_text(encoding="utf-8")
+    issues = check_js_returns_object_schemaless_branch(shipped_source, _MJS_PATH)
+    assert issues == []

package/hooks/blocking/test_env_var_table_code_drift_blocker.py

@@ -0,0 +1,94 @@
+"""Tests for the env-var-table code-drift blocker.
+
+Each test builds a real on-disk directory holding a code file and a markdown
+doc, then drives the blocker's detection function against that tree. The drift
+the blocker catches: a markdown env-var summary table row attributes an
+environment variable to a code file whose source never references that variable.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_blocking_dir = str(Path(__file__).resolve().parent)
+if _blocking_dir not in sys.path:
+    sys.path.insert(0, _blocking_dir)
+
+from env_var_table_code_drift_blocker import (  # noqa: E402
+    find_drift_rows,
+    is_markdown_file,
+)
+
+
+def _write(file_path: Path, content: str) -> None:
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(content, encoding="utf-8")
+
+
+def _anchor_repo_root(repo_root: Path) -> None:
+    (repo_root / ".git").mkdir(parents=True, exist_ok=True)
+
+
+def test_is_markdown_file_accepts_md_and_rejects_python() -> None:
+    assert is_markdown_file("docs/configuration.md") is True
+    assert is_markdown_file("auth/google_auth.py") is False
+
+
+def test_flags_variable_absent_from_named_code_file(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "auth" / "google_auth.py", "def load():\n    return read_bws_secret()\n")
+    doc_path = tmp_path / "docs" / "configuration.md"
+    content = (
+        "## Summary: Environment Variables\n\n"
+        "| Variable | Used By | Purpose |\n"
+        "|----------|---------|---------|\n"
+        "| `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | Path to JSON |\n"
+    )
+    drift_rows = find_drift_rows(content, doc_path.parent)
+    assert drift_rows == ["GOOGLE_APPLICATION_CREDENTIALS -> auth/google_auth.py"]
+
+
+def test_passes_when_variable_present_in_code_file(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(
+        tmp_path / "automation_logging" / "__init__.py",
+        'topic = os.environ["NTFY_TOPIC"]\n',
+    )
+    doc_path = tmp_path / "docs" / "configuration.md"
+    content = (
+        "| Variable | Used By | Purpose |\n"
+        "|----------|---------|---------|\n"
+        "| `NTFY_TOPIC` | `automation_logging/__init__.py` | ntfy topic |\n"
+    )
+    assert find_drift_rows(content, doc_path.parent) == []
+
+
+def test_skips_row_whose_code_file_is_absent(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    doc_path = tmp_path / "docs" / "configuration.md"
+    content = (
+        "| Variable | Used By | Purpose |\n"
+        "|----------|---------|---------|\n"
+        "| `MISSING_VAR` | `nowhere/ghost.py` | unresolved |\n"
+    )
+    assert find_drift_rows(content, doc_path.parent) == []
+
+
+def test_ignores_rows_inside_a_fenced_code_block(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "auth" / "google_auth.py", "no variable here\n")
+    doc_path = tmp_path / "docs" / "configuration.md"
+    content = "```\n| `GOOGLE_APPLICATION_CREDENTIALS` | `auth/google_auth.py` | sample |\n```\n"
+    assert find_drift_rows(content, doc_path.parent) == []
+
+
+def test_ignores_row_whose_second_cell_is_not_a_code_file(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    doc_path = tmp_path / "docs" / "configuration.md"
+    content = (
+        "| Variable | Purpose | Default |\n"
+        "|----------|---------|---------|\n"
+        "| `SOME_FLAG` | `enables the thing` | off |\n"
+    )
+    assert find_drift_rows(content, doc_path.parent) == []

package/hooks/blocking/test_package_inventory_stale_blocker.py

@@ -311,6 +311,52 @@ def test_is_inventoried_production_file_accepts_production_file(tmp_path: Path):
     assert is_inventoried_production_file(str(production_file_path)) is True
 
 
+SKILL_MD_SCRIPTS_LAYOUT = (
+    "# base-theme-match\n\n"
+    "## Layout\n\n"
+    "| Path | Role |\n"
+    "|---|---|\n"
+    "| `scripts/discover_candidates.py` | Discovers candidates. |\n"
+    "| `scripts/resolve_stp.py` | Resolves the STP filename. |\n"
+    "| `scripts/select_stp.py` | Selects the STP filename. |\n"
+)
+
+
+def _skill_scripts_directory(tmp_path: Path) -> Path:
+    """Return a skill package's scripts/ directory under a SKILL.md Layout table."""
+    skill_directory = tmp_path / "base-theme-match"
+    skill_directory.mkdir()
+    (skill_directory / "SKILL.md").write_text(SKILL_MD_SCRIPTS_LAYOUT, encoding="utf-8")
+    scripts_directory = skill_directory / "scripts"
+    scripts_directory.mkdir()
+    _write_sibling_files(scripts_directory, ["discover_candidates.py", "resolve_stp.py"])
+    return scripts_directory
+
+
+def test_blocks_new_script_absent_from_parent_skill_layout(tmp_path: Path):
+    scripts_directory = _skill_scripts_directory(tmp_path)
+    new_file_path = scripts_directory / "stp_selection.py"
+    result = _run_hook(
+        "Write",
+        {"file_path": str(new_file_path), "content": "x = 1\n"},
+    )
+    assert result.returncode == 0
+    payload = json.loads(result.stdout)
+    assert payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "stp_selection.py" in payload["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_allows_new_script_named_in_parent_skill_layout(tmp_path: Path):
+    scripts_directory = _skill_scripts_directory(tmp_path)
+    new_file_path = scripts_directory / "select_stp.py"
+    result = _run_hook(
+        "Write",
+        {"file_path": str(new_file_path), "content": "x = 1\n"},
+    )
+    assert result.returncode == 0
+    assert result.stdout.strip() == ""
+
+
 def test_find_stale_inventory_returns_survey_for_omission(tmp_path: Path):
     package_directory = _package_directory_with_readme(tmp_path, README_LISTING_TWO_FILES)
     _write_sibling_files(package_directory, ["dialer_compose.py", "compose_dialer_cli.py"])

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -632,24 +632,24 @@ def test_dispatcher_write_applies_both_groups() -> None:
     assert "blocking/plain_language_blocker.py" in all_write_script_paths, (
         "plain_language_blocker (Group B) must be in Write applicable set"
     )
-    assert len(all_write_entries) == 18, (
-        f"Write tool must apply to all 18 hosted hooks, got {len(all_write_entries)}"
+    assert len(all_write_entries) == 19, (
+        f"Write tool must apply to all 19 hosted hooks, got {len(all_write_entries)}"
     )
 
 
 def test_dispatcher_edit_applies_both_groups() -> None:
     """Edit tool triggers both Group A and Group B hooks through the dispatcher."""
     all_edit_entries = _applicable_entries_for_tool(EDIT_TOOL_NAME)
-    assert len(all_edit_entries) == 18, (
-        f"Edit tool must apply to all 18 hosted hooks, got {len(all_edit_entries)}"
+    assert len(all_edit_entries) == 19, (
+        f"Edit tool must apply to all 19 hosted hooks, got {len(all_edit_entries)}"
     )
 
 
 def test_dispatcher_multi_edit_applies_only_group_b() -> None:
-    """MultiEdit tool triggers only Group B (7 hooks), not Group A."""
+    """MultiEdit tool triggers only Group B (8 hooks), not Group A."""
     all_multi_edit_entries = _applicable_entries_for_tool(MULTI_EDIT_TOOL_NAME)
-    assert len(all_multi_edit_entries) == 7, (
-        f"MultiEdit tool must apply to exactly 7 Group-B hooks, got {len(all_multi_edit_entries)}"
+    assert len(all_multi_edit_entries) == 8, (
+        f"MultiEdit tool must apply to exactly 8 Group-B hooks, got {len(all_multi_edit_entries)}"
     )
 
 

package/hooks/hooks_constants/CLAUDE.md

@@ -13,6 +13,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
 | `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
 | `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
+| `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
 | `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
 | `code_verifier_spawn_preflight_gate_constants.py` | Subagent type, merge-tree command flags, timeouts, and deny-message text for the code-verifier spawn pre-flight gate |
 | `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |

package/hooks/hooks_constants/blocking_check_limits.py

@@ -45,12 +45,14 @@ ALL_IMPORT_BLOCK_SORT_RUFF_COMMAND_PREFIX: tuple[str, ...] = (
     "json",
 )
 MAX_JS_RESUME_TASK_ENUMERATION_ISSUES: int = 5
+MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES: int = 5
 MINIMUM_RESUME_TASK_ENUMERATION_ITEMS: int = 2
 DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
 MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
 DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
 MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES: int = 3
 MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES: int = 3
+MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES: int = 3
 MAX_STALE_TEST_NAME_TARGET_ISSUES: int = 3
 STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT: int = 2
 MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES: int = 5
@@ -79,6 +81,36 @@ MINIMUM_TOKENS_FOR_DISPATCH_CALLEE: int = 2
 MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES: int = 3
 MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES: int = 5
 SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT: int = 1
+MAX_LENGTH_CONSTANT_SUPERLATIVE_ISSUES: int = 3
+LENGTH_GATE_PACKAGE_SCAN_FILE_LIMIT: int = 400
+LENGTH_CONFIG_SUBDIRECTORY_NAME: str = "config"
+ALL_LENGTH_CONSTANT_NAME_SUFFIXES: tuple[str, ...] = ("_LENGTH", "_LEN")
+ALL_LENGTH_SUPERLATIVE_RANGE_PHRASES: tuple[str, ...] = (
+    "longest",
+    "maximum length",
+    "no longer than",
+)
+MAX_DOCSTRING_FIELD_RUNMODE_OUTCOME_ISSUES: int = 5
+ALL_DOCSTRING_RUNMODE_FLAG_FIELD_NAME_TOKENS: tuple[str, ...] = ("dry_run",)
+ALL_DOCSTRING_PER_RECORD_WRITE_OUTCOME_PHRASES: tuple[str, ...] = (
+    "was written",
+    "is written",
+    "were written",
+    "nothing was written",
+    "no file was written",
+    "wrote",
+    "written to disk",
+    "written to the file",
+)
+ALL_DOCSTRING_RUN_MODE_PHRASES: tuple[str, ...] = (
+    "dry run",
+    "dry-run",
+    "execute run",
+    "--execute",
+    "run mode",
+    "live run",
+    "not an execute",
+)
 MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES: int = 5
 DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME: str = "LargeZipFile"
 ZIPFILE_WRITER_CLASS_NAME: str = "ZipFile"
@@ -187,6 +219,26 @@ ALL_DOCSTRING_GUARDED_FAILURE_CLAIM_PHRASES: tuple[str, ...] = (
     "malformed payload yields none",
 )
 
+ALL_DOCSTRING_NO_NETWORK_CLAIM_PHRASES: tuple[str, ...] = (
+    "without touching the network",
+    "without touching the share",
+    "without touching the network share",
+    "without hitting the network",
+    "without hitting the share",
+    "without a network call",
+    "without any network call",
+    "without network access",
+    "without a network round-trip",
+    "without a network round trip",
+    "no network access",
+    "no network round-trip",
+    "no network round trip",
+)
+
+ALL_PATH_METADATA_ACCESS_METHOD_NAMES: frozenset[str] = frozenset(
+    {"is_file", "is_dir", "exists", "stat", "lstat"}
+)
+
 MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES: int = 3
 ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES: tuple[str, ...] = (
     "no literals appear inline",
@@ -228,3 +280,30 @@ ALL_TEST_INDICATING_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
         "UNIT_TEST",
     }
 )
+
+MAX_MODULE_DOCSTRING_DATA_SCHEMA_SCOPE_ISSUES: int = 1
+MODULE_DOCSTRING_DATA_SCHEMA_CONSTANT_SAMPLE_LIMIT: int = 6
+ALL_USER_FACING_TEXT_SCOPE_DOCSTRING_PHRASES: tuple[str, ...] = (
+    "user-facing",
+    "user facing",
+)
+ALL_DATA_SCHEMA_CONSTANT_NAME_MARKERS: tuple[str, ...] = (
+    "_FIELD_",
+    "_KEY_",
+    "_SCHEMA_",
+    "_ENCODING",
+    "_FORMAT_STRING",
+)
+ALL_DATA_SCHEMA_DOCSTRING_ACKNOWLEDGEMENT_PHRASES: tuple[str, ...] = (
+    "field key",
+    "schema key",
+    "schema",
+    "metadata",
+    "encoding",
+    "format string",
+    "runtime config",
+    "runtime-config",
+    "data schema",
+    "data-schema",
+    "config constant",
+)

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -39,6 +39,20 @@ DENY_REASON_ISSUE_PREVIEW_COUNT = 10
 ALL_BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_", "was_", "did_")
 UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
 
+ALL_POLARITY_ANTONYM_TOKEN_PAIRS: tuple[tuple[str, str], ...] = (
+    ("allowed", "forbidden"),
+    ("allowed", "denied"),
+    ("allowed", "blocked"),
+    ("permitted", "forbidden"),
+    ("permitted", "denied"),
+    ("included", "excluded"),
+    ("valid", "invalid"),
+    ("enabled", "disabled"),
+    ("visible", "hidden"),
+    ("present", "missing"),
+)
+POLARITY_TOKEN_BOUNDARY_PATTERN: str = r"(?:^|_)%s(?:_|$)"
+
 ALL_MUST_CHECK_RETURN_FUNCTION_NAMES: frozenset[str] = frozenset({"find_and_click", "write_outcome"})
 
 DOCSTRING_ARG_ENTRY_PATTERN: re.Pattern[str] = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*[:(]")
@@ -208,6 +222,20 @@ ENUMERATION_TASK_ITEM_PATTERN: re.Pattern[str] = re.compile(
 HYPHENATED_TASK_ITEM_PATTERN: re.Pattern[str] = re.compile(
     r"^[a-z0-9]+(?:-[a-z0-9]+)+$"
 )
+FUNCTION_WITH_JSDOC_PATTERN: re.Pattern[str] = re.compile(
+    r"/\*\*(?P<jsdoc>(?:(?!\*/).)*?)\*/\s*"
+    r"(?:async\s+)?function\s+(?P<name>\w+)\s*\(",
+    re.DOTALL,
+)
+JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN: re.Pattern[str] = re.compile(
+    r"@returns?\s*\{[^}]*Promise\s*<\s*[Oo]bject\s*>[^}]*\}"
+)
+RETURN_CALL_OPENING_PARENTHESIS_PATTERN: re.Pattern[str] = re.compile(
+    r"\breturn\s+(?:await\s+)?(?P<callee>\w+)\s*\("
+)
+SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![A-Za-z0-9_])schema\s*:"
+)
 ALL_BUILTIN_DICT_METHOD_NAMES: frozenset[str] = frozenset({
     "get", "items", "keys", "values", "update", "pop",
     "setdefault", "copy", "clear",

package/hooks/hooks_constants/env_var_table_code_drift_constants.py

@@ -0,0 +1,64 @@
+"""Constants for the env-var-table code-drift blocker.
+
+Holds the markdown filename matcher, the table-row and cell patterns, the
+env-var-name and code-file-extension recognizers, the bounded-scan budgets, and
+the block-message strings. The blocker imports each of these by name.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "MARKDOWN_FILE_EXTENSION",
+    "TABLE_ROW_PATTERN",
+    "CODE_FENCE_PATTERN",
+    "SEPARATOR_CELL_PATTERN",
+    "BACKTICK_TOKEN_PATTERN",
+    "ENV_VAR_NAME_PATTERN",
+    "ALL_CODE_FILE_EXTENSIONS",
+    "ALL_NOISE_DIRECTORY_NAMES",
+    "GIT_DIRECTORY_NAME",
+    "MINIMUM_ENV_VAR_ROW_CELL_COUNT",
+    "MAX_SUBTREE_FILES_SCANNED",
+    "MAX_DRIFT_ISSUES",
+    "DRIFT_MESSAGE_TEMPLATE",
+    "DRIFT_ADDITIONAL_CONTEXT",
+    "DRIFT_SYSTEM_MESSAGE",
+]
+
+MARKDOWN_FILE_EXTENSION = ".md"
+
+TABLE_ROW_PATTERN = re.compile(r"^\s*\|")
+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"}
+)
+ALL_NOISE_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {".git", "__pycache__", "node_modules", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
+)
+
+GIT_DIRECTORY_NAME = ".git"
+MINIMUM_ENV_VAR_ROW_CELL_COUNT = 2
+
+MAX_SUBTREE_FILES_SCANNED = 20000
+MAX_DRIFT_ISSUES = 20
+
+DRIFT_MESSAGE_TEMPLATE = (
+    "Env-var summary table in {file} attributes an environment variable to a "
+    "code file that does not read it: {drift}. The code file no longer "
+    "references the variable, so the table points a reader at a consumer "
+    "relationship the code does not have. Remove or correct the row so the "
+    "summary matches the code."
+)
+DRIFT_ADDITIONAL_CONTEXT = (
+    "Each `VARIABLE` | `code/file.py` row in a markdown env-var summary table "
+    "names a code file that reads that variable. When the code file exists but "
+    "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."

package/hooks/hooks_constants/package_inventory_stale_blocker_constants.py

@@ -1,7 +1,8 @@
 """Constants for the package-inventory stale-entry blocker.
 
 A package directory documents its own files in a sibling inventory document —
-a ``README.md`` Layout table or a ``CLAUDE.md`` "Key files" list — whose entries
+a ``README.md`` Layout table, a ``CLAUDE.md`` "Key files" list, or a skill
+``SKILL.md`` Layout table that maps the ``scripts/`` subdirectory — whose entries
 name each file in backticks. When a new production code file lands in that
 directory and the inventory carries no entry naming it, the inventory disagrees
 with the directory on the package's file set, and a reader trusting the
@@ -19,6 +20,8 @@ import re
 
 __all__ = [
     "ALL_INVENTORY_DOCUMENT_NAMES",
+    "SKILL_INVENTORY_DOCUMENT_NAME",
+    "SCRIPTS_SUBDIRECTORY_NAME",
     "ALL_PRODUCTION_CODE_EXTENSIONS",
     "PYTHON_FILE_EXTENSION",
     "ALL_TEST_FILE_MARKERS",
@@ -35,7 +38,13 @@ __all__ = [
     "STALE_INVENTORY_ADDITIONAL_CONTEXT",
 ]
 
-ALL_INVENTORY_DOCUMENT_NAMES: frozenset[str] = frozenset({"README.md", "CLAUDE.md"})
+SKILL_INVENTORY_DOCUMENT_NAME: str = "SKILL.md"
+
+SCRIPTS_SUBDIRECTORY_NAME: str = "scripts"
+
+ALL_INVENTORY_DOCUMENT_NAMES: frozenset[str] = frozenset(
+    {"README.md", "CLAUDE.md", SKILL_INVENTORY_DOCUMENT_NAME}
+)
 
 PYTHON_FILE_EXTENSION: str = ".py"
 
@@ -96,16 +105,18 @@ STALE_INVENTORY_MESSAGE_TEMPLATE: str = (
 
 STALE_INVENTORY_SYSTEM_MESSAGE: str = (
     "New production file is absent from its package inventory (README.md / "
-    "CLAUDE.md) - add the inventory entry in this same change"
+    "CLAUDE.md / SKILL.md) - add the inventory entry in this same change"
 )
 
 STALE_INVENTORY_ADDITIONAL_CONTEXT: str = (
-    "A package directory whose README.md or CLAUDE.md lists its files in "
-    "backticks is a maintained inventory of the package's file set. A new "
-    "production code file (.py, .mjs, .js, .ts, .ps1, .sh) in that directory "
-    "carries one inventory entry naming it. Add a row to the README.md table or "
-    "a bullet to the CLAUDE.md list naming this file, describing what it does, "
-    "in the same change that creates the file. Exempt files (no entry needed): "
+    "A package directory whose README.md, CLAUDE.md, or SKILL.md lists its files "
+    "in backticks is a maintained inventory of the package's file set. A skill "
+    "SKILL.md Layout table that maps the scripts/ subdirectory counts as the "
+    "inventory for files in that subdirectory. A new production code file (.py, "
+    ".mjs, .js, .ts, .ps1, .sh) in an inventoried directory carries one entry "
+    "naming it. Add a row to the README.md or SKILL.md table or a bullet to the "
+    "CLAUDE.md list naming this file, describing what it does, in the same change "
+    "that creates the file. Exempt files (no entry needed): "
     "__init__.py, conftest.py, setup.py, _path_setup.py, files under config/ or "
     "tests/, and test files (test_*.py, *_test.py, *.spec.*, *.test.*)."
 )

package/hooks/hooks_constants/paired_test_coverage_constants.py

@@ -21,7 +21,15 @@ MINIMUM_COVERED_PUBLIC_FUNCTIONS: int = 1
 MAX_PAIRED_TEST_COVERAGE_ISSUES: int = 25
 MISSING_PAIRED_TEST_GUIDANCE: str = (
     "is exercised by no test in the module's paired test suite, though that"
-    " suite already covers another public function in this module - add a"
-    " behavioral test that calls this function and asserts on its return value"
-    " or side effect (CODE_RULES TDD paired-test rule)"
+    " suite already exercises this module (covering another public function or"
+    " referencing a private helper) - add a behavioral test that calls this"
+    " function and asserts on its return value or side effect (CODE_RULES TDD"
+    " paired-test rule)"
+)
+TEST_SUITE_OMITS_FUNCTION_GUIDANCE: str = (
+    "is a public function this stem-matched test suite defines its module for"
+    " but exercises nowhere, though the suite already covers another public"
+    " function in that module - add a behavioral test that calls this function"
+    " and asserts on its return value or side effect, or remove the function"
+    " (CODE_RULES TDD paired-test rule)"
 )

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -129,6 +129,10 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         script_relative_path="blocking/package_inventory_stale_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/env_var_table_code_drift_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
     HostedHookEntry(
         script_relative_path="blocking/pytest_testpaths_orphan_blocker.py",
         applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,