claude-dev-env 1.82.0 → 1.84.0

package/hooks/hooks_constants/stale_comment_reference_blocker_constants.py

@@ -0,0 +1,76 @@
+"""Configuration constants for the PreToolUse hook stale_comment_reference_blocker."""
+
+from re import Pattern, compile
+
+COMMENT_IDENTIFIER_PATTERN: Pattern[str] = compile(r"[A-Za-z_][A-Za-z0-9_]{2,}")
+
+ALL_COMMENT_STOPWORDS: frozenset[str] = frozenset(
+    {
+        "the",
+        "and",
+        "for",
+        "not",
+        "with",
+        "from",
+        "into",
+        "onto",
+        "out",
+        "off",
+        "this",
+        "that",
+        "these",
+        "those",
+        "each",
+        "all",
+        "any",
+        "are",
+        "was",
+        "were",
+        "has",
+        "have",
+        "had",
+        "its",
+        "use",
+        "uses",
+        "used",
+        "using",
+        "when",
+        "then",
+        "than",
+        "before",
+        "after",
+        "only",
+        "also",
+        "but",
+        "per",
+        "via",
+        "one",
+        "two",
+        "new",
+        "old",
+        "now",
+    }
+)
+
+PYTHON_FILE_SUFFIX: str = ".py"
+
+COMMENT_LINE_PREFIX: str = "#"
+
+STALE_COMMENT_DENY_TEMPLATE: str = (
+    "The comment above the changed line in {file_path} names "
+    "'{orphaned_name}', which this edit removes from the line below. "
+    "The comment left in place reads: {contradicted_comment}. "
+    "Update or remove the comment in the same edit."
+)
+
+STALE_COMMENT_ADDITIONAL_CONTEXT: str = (
+    "A standalone comment directly above an edited line describes that "
+    "line. When the edit drops a name the comment carries, rewrite the "
+    "comment to describe the rewritten line, or delete the comment, inside "
+    "the same Edit call."
+)
+
+STALE_COMMENT_SYSTEM_MESSAGE: str = (
+    "Agent edited a code line without updating the comment above it that "
+    "names what the edit removed"
+)

package/hooks/hooks_constants/state_description_blocker_constants.py

@@ -41,6 +41,14 @@ ALL_COMMENT_TRANSITION_PATTERNS: list[Pattern[str]] = [
 
 CODE_FENCE_PATTERN: Pattern[str] = compile(r"```[\s\S]*?```")
 INLINE_CODE_PATTERN: Pattern[str] = compile(r"``[^`]+``|`[^`]+`")
+DOUBLE_QUOTED_SPAN_PATTERN: Pattern[str] = compile(r'"[^"\n]*"')
+TRIPLE_QUOTED_BLOCK_PATTERN: Pattern[str] = compile(
+    r'"""([\s\S]*?)"""|\'\'\'([\s\S]*?)\'\'\''
+)
+
+PYTHON_EXTENSION: str = ".py"
+
+ALL_DEFINITION_HEADER_PREFIXES: tuple[str, ...] = ("def ", "async def ", "class ")
 
 ALL_MARKDOWN_EXTENSIONS: frozenset[str] = frozenset(
     {".md", ".mdx", ".markdown", ".rmd"}

package/hooks/validation/post_tool_use_dispatcher.py

@@ -168,7 +168,7 @@ class PostDispatcherDecision:
         all_block_reasons: All block reasons from blocking hooks, in run order.
         all_non_block_stdout: Stdout from hooks that did not emit a block
             decision, concatenated in run order. Preserved so informational
-            output (such as the doc-gist htmlpreview URL) reaches the harness
+            output (such as an auto-formatter notice) reaches the harness
             on both the allow and block paths.
     """
 

package/hooks/validation/test_post_tool_use_dispatcher.py

@@ -5,11 +5,11 @@ hook as its own subprocess (the production path), records each hook's block
 decision, computes the expected aggregate, then runs the dispatcher on the same
 payload and asserts an equal block-or-allow decision and the union of reasons.
 
-Three focused tests pin the side-effecting behavior the dispatcher must not
+Two focused tests pin the side-effecting behavior the dispatcher must not
 change: the formatter formats only on a Write of a file git does not yet track
-and never blocks; the type-checker still blocks on a real type error when run
-through the dispatcher; and non-block stdout from side-effect hooks (such as
-the doc-gist htmlpreview URL) survives on both the allow and block paths.
+and never blocks; and the type-checker still blocks on a real type error when
+run through the dispatcher. Two more tests pin that non-block stdout from a
+side-effect hook survives on both the allow and block paths.
 
 Crash and early-exit tests exercise the aggregator directly: an early hook
 crash before mypy does not drop mypy's block, a non-blocking hook crash leaves
@@ -20,6 +20,7 @@ from __future__ import annotations
 
 import importlib.util
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -33,9 +34,6 @@ _VALIDATION_DIR_STR = str(Path(__file__).resolve().parent)
 if _VALIDATION_DIR_STR not in sys.path:
     sys.path.insert(0, _VALIDATION_DIR_STR)
 
-from hooks_constants.doc_gist_auto_publish_constants import (  # noqa: E402, I001
-    HOOK_SUBPROCESS_TIMEOUT_SECONDS as DOC_GIST_TIMEOUT_SECONDS,
-)
 from hooks_constants.post_tool_use_dispatcher_constants import (  # noqa: E402, I001
     ALL_POST_HOSTED_HOOK_ENTRIES,
     BLOCK_DECISION,
@@ -95,6 +93,26 @@ def _resolve_extra_arguments(each_entry: PostHostedHookEntry) -> list[str]:
     return resolved_arguments
 
 
+def _environment_without_git_hook_variables() -> dict[str, str]:
+    """Return the process environment with git's hook-scoped variables removed.
+
+    Git exports variables such as GIT_DIR and GIT_INDEX_FILE to hook
+    processes. When this suite runs under a git hook (the pre-commit gate
+    replays staged test files), those variables leak into the hook
+    subprocesses and point their project discovery at the wrong checkout.
+    Stripping them restores the cwd-based discovery the hooks use in
+    production.
+
+    Returns:
+        A copy of the environment without any GIT_-prefixed variable.
+    """
+    return {
+        each_name: each_value
+        for each_name, each_value in os.environ.items()
+        if not each_name.startswith("GIT_")
+    }
+
+
 def _run_hook_subprocess(
     each_entry: PostHostedHookEntry, payload_text: str
 ) -> subprocess.CompletedProcess[str]:
@@ -116,6 +134,7 @@ def _run_hook_subprocess(
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_environment_without_git_hook_variables(),
     )
 
 
@@ -135,6 +154,7 @@ def _run_dispatcher(payload_text: str) -> subprocess.CompletedProcess[str]:
         capture_output=True,
         text=True,
         encoding="utf-8",
+        env=_environment_without_git_hook_variables(),
     )
 
 
@@ -267,10 +287,10 @@ def _post_tool_use_dispatcher_harness_timeout_seconds() -> int:
 def _hosted_hooks_worst_case_internal_seconds() -> int:
     """Return the summed worst-case internal subprocess budget of the hosted hooks.
 
-    The three hosted hooks run sequentially in one dispatcher process. The
-    type-checker, the formatter (its slower JS path), and the doc-gist publisher
-    each carry their own internal subprocess timeout; their sum is the dispatcher
-    process's worst-case runtime when each hook runs to its own ceiling.
+    The hosted hooks run sequentially in one dispatcher process. The
+    type-checker and the formatter (its slower JS path) each carry their own
+    internal subprocess timeout; their sum is the dispatcher process's
+    worst-case runtime when each hook runs to its own ceiling.
 
     Returns:
         The summed worst-case internal subprocess seconds across the hosted hooks.
@@ -281,21 +301,17 @@ def _hosted_hooks_worst_case_internal_seconds() -> int:
         auto_formatter.PYTHON_FORMAT_TIMEOUT_SECONDS,
         auto_formatter.JS_FORMAT_TIMEOUT_SECONDS,
     )
-    return (
-        mypy_validator.MYPY_TIMEOUT_SECONDS
-        + slowest_formatter_seconds
-        + DOC_GIST_TIMEOUT_SECONDS
-    )
+    return mypy_validator.MYPY_TIMEOUT_SECONDS + slowest_formatter_seconds
 
 
 def test_dispatcher_harness_timeout_clears_summed_hosted_hook_budgets() -> None:
     """The dispatcher harness timeout exceeds the summed worst-case hosted-hook budget.
 
-    The three hosted hooks run sequentially under one harness timeout. When the
+    The hosted hooks run sequentially under one harness timeout. When the
     harness timeout does not clear their summed worst-case internal budgets, a
     near-full slow type-check run consumes the budget and the harness kills the
-    dispatcher before the formatter and doc-gist publisher get their turn. The
-    harness timeout must exceed the sum so every hosted hook runs to completion.
+    dispatcher before the formatter gets its turn. The harness timeout must
+    exceed the sum so every hosted hook runs to completion.
     """
     harness_timeout_seconds = _post_tool_use_dispatcher_harness_timeout_seconds()
     summed_internal_seconds = _hosted_hooks_worst_case_internal_seconds()
@@ -303,7 +319,7 @@ def test_dispatcher_harness_timeout_clears_summed_hosted_hook_budgets() -> None:
         "PostToolUse dispatcher harness timeout "
         f"({harness_timeout_seconds}s) must exceed the summed worst-case internal "
         f"budgets of the hosted hooks ({summed_internal_seconds}s), or a slow "
-        "type-check run starves the formatter and doc-gist publisher."
+        "type-check run starves the formatter."
     )
 
 
@@ -315,14 +331,14 @@ def test_clean_edit_of_plain_text_allows() -> None:
 
 
 def test_clean_write_of_nonexistent_path_allows() -> None:
-    """Dispatcher allows a Write whose path does not exist (mypy and doc-gist skip)."""
+    """Dispatcher allows a Write whose path does not exist (mypy skips)."""
     missing_path = str(_VALIDATION_DIR / "does_not_exist_dispatcher_probe.txt")
     payload_text = _write_payload(missing_path, "hello world\n")
     _assert_dispatcher_matches_individual_hooks(payload_text)
 
 
-def test_edit_of_non_html_skips_doc_gist_allows() -> None:
-    """Dispatcher allows an Edit of an existing non-HTML file with no sentinel."""
+def test_edit_of_non_html_allows() -> None:
+    """Dispatcher allows an Edit of an existing non-HTML file."""
     existing_path = str(Path(__file__).resolve())
     payload_text = _edit_payload(existing_path, "old", "new")
     _assert_dispatcher_matches_individual_hooks(payload_text)
@@ -433,10 +449,10 @@ def test_formatter_formats_only_untracked_write_and_never_blocks(tmp_path: Path)
 def test_non_block_stdout_preserved_in_aggregator_allow_path() -> None:
     """Aggregator preserves non-block hook stdout on the allow path.
 
-    A side-effect hook (such as doc_gist_auto_publish) writes informational
-    text to stdout without emitting a block decision. The aggregator must carry
-    that text into all_non_block_stdout so the dispatcher can write it to the
-    real stdout on the allow path.
+    A side-effect hook writes informational text to stdout without emitting a
+    block decision. The aggregator must carry that text into
+    all_non_block_stdout so the dispatcher can write it to the real stdout on
+    the allow path.
     """
     informational_text = "https://htmlpreview.github.io/?https://gist.github.com/abc/123"
     all_results = [
@@ -459,7 +475,7 @@ def test_non_block_stdout_preserved_in_aggregator_allow_path() -> None:
 def test_non_block_stdout_preserved_in_aggregator_block_path() -> None:
     """Aggregator preserves non-block hook stdout even when another hook blocks.
 
-    When mypy_validator blocks and doc_gist_auto_publish wrote informational
+    When mypy_validator blocks and a side-effect hook wrote informational
     text, both the block reason and the informational text survive in the
     aggregated decision so _emit_block_decision can forward both to stdout.
     """
@@ -512,9 +528,9 @@ def test_early_hook_crash_does_not_drop_later_blocking_hook_block() -> None:
 def test_non_blocking_hook_crash_leaves_decision_allow() -> None:
     """A crash in a non-blocking hook does not change an allow to a block.
 
-    A side-effect hook such as auto_formatter or doc_gist_auto_publish carries
-    is_blocking=False. Its crash must not surface a blocking signal — the
-    aggregated decision stays allow.
+    A side-effect hook such as auto_formatter carries is_blocking=False. Its
+    crash must not surface a blocking signal — the aggregated decision stays
+    allow.
     """
     all_results = [
         PostHostedHookResult(captured_stdout="", did_crash=True, is_blocking=False),
@@ -566,12 +582,12 @@ def test_block_path_emits_single_parseable_json_object_on_stdout() -> None:
     )
     try:
         payload_text = _write_payload(str(type_error_file), type_error_file.read_text())
-        direct_block, _direct_reason = _parse_block_decision(
-            _run_hook_subprocess(ALL_POST_HOSTED_HOOK_ENTRIES[0], payload_text)
-        )
+        completed_direct = _run_hook_subprocess(ALL_POST_HOSTED_HOOK_ENTRIES[0], payload_text)
+        direct_block, _direct_reason = _parse_block_decision(completed_direct)
         assert direct_block, (
             "Precondition failed: mypy_validator did not block a real type error directly. "
-            "Is mypy installed and the file inside the git project?"
+            "Is mypy installed and the file inside the git project?\n"
+            f"stdout: {completed_direct.stdout!r}\nstderr: {completed_direct.stderr!r}"
         )
 
         dispatcher_result = _run_dispatcher(payload_text)

package/hooks/workflow/CLAUDE.md

@@ -1,22 +1,16 @@
 # hooks/workflow
 
-PostToolUse hooks that trigger side-effects after Claude writes a file. They do not block writes; they produce companion artifacts or publish content automatically.
+PostToolUse hooks that run after Claude writes a file. They do not block the write; they run follow-up side effects — reformatting the written file and resetting the investigation tracker.
 
 ## Key files
 
 | File | Event | What it does |
 |---|---|---|
 | `auto_formatter.py` | PostToolUse (Write/Edit) | Runs the project's auto-formatter (ruff, prettier, etc.) on the written file and sends a desktop notification when formatting changes are applied |
-| `doc_gist_auto_publish.py` | PostToolUse (Write on `.html` files) | When an `.html` file has the `<!-- @publish-as-gist -->` marker, uploads it as a secret GitHub Gist and prints the htmlpreview URL into the harness output |
-| `md_to_html_companion.py` | PostToolUse (Write/Edit on `.md` files) | Generates a styled `.html` companion file from the `.md` source with dark-mode styling |
 | `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
 | `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
-| `test_doc_gist_auto_publish.py` | — | Tests for `doc_gist_auto_publish.py` |
-| `test_md_to_html_companion.py` | — | Tests for `md_to_html_companion.py` |
 
 ## Conventions
 
-- All three main hooks exit 0 even on failure — they log warnings to stderr but do not break Claude's flow.
-- `doc_gist_auto_publish.py` checks for the `<!-- @publish-as-gist -->` marker before doing any work; HTML files without it are ignored.
-- Constants (marker text, blocked URL schemes, gist upload script path) live in `hooks_constants/doc_gist_auto_publish_constants.py` and `hooks_constants/html_companion_constants.py`.
+- `auto_formatter.py` exits 0 even on failure — it logs warnings to stderr but does not break Claude's flow.
 - Tests run with `python -m pytest workflow/test_<name>.py`.

package/package.json

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

package/rules/CLAUDE.md

@@ -28,11 +28,12 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
 | `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
 | `env-var-table-code-drift.md` | Every env-var summary table row in a `.md` file names a code file whose source references the variable |
+| `es-exe-file-search.md` | File search on Windows routes through the `es.exe` CLI with a scoped query; the Everything HTTP server stays off |
 | `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
 | `package-inventory-stale-entry.md` | A new production code file added to a directory carries an entry in that directory's `README.md`/`CLAUDE.md` file inventory |
 | `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
 | `parallel-tools.md` | Make all independent tool calls in a single response |
-| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and paints a concrete scene a general developer follows on first read; a run-on backstop hook plus Category O9 audit enforce it |
+| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
@@ -42,8 +43,10 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
 | `testing.md` | Test quality and infrastructure standards |
 | `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
-| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking the user |
+| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
+| `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
 | `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
+| `workers-done-before-complete.md` | A task reaches `completed` only when every spawned worker has finished and its results are merged into run state |
 | `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
 
 ## Hook enforcement

package/rules/claude-md-orphan-file.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/CLAUDE.md"
+---
+
 # Orphan File Reference in a Per-Directory CLAUDE.md
 
 **When this applies:** Any Write, Edit, or MultiEdit to a file named `CLAUDE.md` that lists files in a markdown table whose first column names each file in backticks, or that shows run commands invoking those files inside fenced code blocks.

package/rules/docstring-prose-matches-implementation.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.md"
+---
+
 # Docstring Prose Matches Implementation
 
 **When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
@@ -6,7 +12,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Ten more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_names_absent_type_checking_gate` covers a module or function docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, while no identifier in the module's code carries the `type_checking` marker — the drift where the prose points a reader at a gate the body never performs; drop the `TYPE_CHECKING` gate wording, or add the detection the prose describes. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the eleven gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Eleven more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_delegation_summary_enumeration_drift` covers a thin delegating wrapper's docstring summary enumerating actions that the same-named function's summary in the named sibling file omits, compared from both save directions. `check_docstring_names_absent_type_checking_gate` covers a module or function docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, while no identifier in the module's code carries the `type_checking` marker — the drift where the prose points a reader at a gate the body never performs; drop the `TYPE_CHECKING` gate wording, or add the detection the prose describes. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the twelve gated slices.
 
 ## What to check before you write the docstring
 
@@ -16,8 +22,11 @@ Read the body and the docstring side by side:
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
+- **Delegation pointer summaries.** A thin delegating method whose docstring names its actions and points at the home of the real body (Apply Russia, review note, publication edits; full doc on `listing_edit_flow`) lists the same actions the delegated function's own summary lists. When an edit moves one action out of the delegated body, the same edit rewords both summaries. The `check_docstring_delegation_summary_enumeration_drift` gate blocks this drift as either side lands: a saved wrapper docstring gets compared against the delegated body beside it, and a saved delegated body gets compared against every neighboring wrapper docstring pointing at it. A conditional bullet in the delegated prose (`re-apply the privacy policy after the upload`) also names every exception the body honors (`unless the reopened button reads Re-register`) — that conditional-completeness slice stays a judgment call for the audit lane.
 - **JS/`.mjs` resume-task enumerations.** A `spawn<Role>Agent` JSDoc that enumerates its sibling `resume<Role>Agent`'s resume tasks in a parenthetical `resume (repair-verify, hardening-verify)` list names every `task === '<name>'` branch the resume body dispatches on. The `check_js_resume_task_enumeration_coverage` gate blocks the JavaScript form of this drift — a spawn JSDoc whose resume enumeration omits a dispatched task — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
 - **JS/`.mjs` `@returns` object with a schema-less branch.** A `function` whose JSDoc `@returns {Promise<object>}` promises a structured object names a return type every branch honors. When the body returns one agent-spawn helper both with a `schema` options object and without one, the schema-less branch resolves to a transcript string, not the object the JSDoc claims. The `check_js_returns_object_schemaless_branch` gate blocks this drift — a `Promise<object>` JSDoc whose body returns the same helper with and without a `schema` key — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
+- **JS/`.mjs` sibling return-object key drift.** Every return path of a function that yields the same record carries the same keys. When an early return in a workflow body omits exactly one key its sibling tail return carries (`allDeferredPrs`), a caller reading that key off the short path gets undefined where the documented contract and the sibling return both promise it. The `check_js_sibling_return_object_key_drift` gate blocks this drift — a `return { ... }` object literal whose key set misses exactly one key of a sibling return in the same function or module scope, with discriminated-union variants and two-or-more-key exit shapes left alone — at Write/Edit time. This is the `.mjs` slice of the same Category O standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
+- **JS/`.mjs` bare-flag return directive vs a stated full-result contract.** A converge-workflow preamble that states a full result-object contract (`{sha, clean:false, down:true, findings:[]}`) and adds "never a bare down flag" matches any `return <flag>: true`/`false` prose directive elsewhere in the file that repeats a status flag the stated contract rules out. When a step's prose says to "return down: true" once a budget runs out, that directive repeats the bare flag the preamble rules out — a StructuredOutput run whose schema needs every field would reject a lone `{down:true}`. The `check_js_bare_flag_return_directive` gate blocks this drift — a `return <name>: true`/`false` prose directive anywhere in the file that repeats a status flag a stated contract rules out, with no proximity or ordering check between the two — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
 - **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
 - **Length-constant superlative vs exact gate.** A module docstring that describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`, `no longer than`) matches how the code consumes the constant. When the only consumer compares `len(...)` against the constant with `==`/`!=` — an exact-length gate where every other length is rejected, not accepted at a shorter length — the superlative prose claims a range of accepted lengths the code never allows. State the exact required length (`the exact #AARRGGBB length`), not a longest/range form. The `check_docstring_length_constant_superlative_vs_exact_gate` gate blocks this drift at Write/Edit time, scanning the constant module's package tree so it sees a consumer that lives in a sibling module; a constant genuinely used as a ceiling (`len(x) <= LIMIT`) is left alone.
 - **Args single-line scope vs span body.** An `Args:` entry that scopes a finding to one named line (`a finding blocks only when its block-anchor line is among the changed lines`) matches the line breadth the body scopes by. When the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper that blocks when any line of the span is among the changed lines, the single-line Args wording understates the scope: an edit touching a non-anchor line of the span still blocks. State the Args entry on the same span breadth the body uses (`a finding blocks when any line of its block span is among the changed lines`). The `check_docstring_args_single_line_scope_vs_span` gate blocks the single-line-Args-over-span-body form of this drift at Write/Edit time.

package/rules/env-var-table-code-drift.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.md"
+---
+
 # Env-Var Summary Table Names a Code File That Reads the Variable
 
 **When this applies:** Any Write, Edit, or MultiEdit to a markdown (`.md`) file that carries an environment-variable summary table — a markdown table whose rows pair a `` `VARIABLE` `` name with the `` `code/file.py` `` that reads it.

package/rules/es-exe-file-search.md

@@ -0,0 +1,17 @@
+# File Search Through the es.exe CLI
+
+**When this applies:** Any file-system search on Windows — finding files by name, path, extension, size, or date modified.
+
+## Rule
+
+`es.exe` (the Everything command-line tool) is the file-search tool. Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds — narrow the search to what you need.
+
+When `es.exe` fails or returns nothing, try to self heal. If self-healing fails, prompt user with askuserquestion with an analysis, plus next steps questions. ie: fall back to `Glob` (name and path patterns) or `Grep` (file contents), and report the outage so the reader knows the index was unavailable.
+
+## Registry tokens
+
+The `es_exe_path_rewriter` hook resolves scope tokens before the command runs. A `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` becomes its quoted absolute path in the command. The hook allows and rewrites — it never blocks — so a search scoped to a registered project names the project token and lets the hook fill in the path.
+
+## Operator syntax
+
+`skills/everything-search/SKILL.md` holds the full operator reference: `ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT, output flags, and the junction/drive-mapping note.

package/rules/no-historical-clutter.md

@@ -1,5 +1,12 @@
 ---
-paths: **/*
+paths:
+  - "**/*.md"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.ps1"
+  - "**/*.sh"
 ---
 
 # No Historical Clutter in Documentation or Comments
@@ -8,10 +15,14 @@ paths: **/*
 
 **Hook enforcement:** `state-description-blocker` (PreToolUse on Write|Edit) blocks historical/comparative language automatically. See `hooks.json` for registration.
 
+Coverage spans `.md` prose, code comments, and Python module/class/function docstrings; a phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped.
+
 ## Rule
 
 Never reference removed implementations, old defaults, prior behaviors, or how something `"used to be"` when updating documentation. The current state is all that matters.
 
+A module or function docstring carries the same describe-current-state-only contract as a `.md` file.
+
 ## Examples of prohibited patterns
 
 ### In documentation (.md files)

package/rules/orphan-css-class.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.py"
+---
+
 # Orphan CSS Class in Generated Markup
 
 **When this applies:** Any Write or Edit to a production `.py` file that builds HTML by emitting `class="..."` attributes inside string literals and pairs them with a `<style>` block — in the same file or in a companion module beside it.

package/rules/package-inventory-stale-entry.md

@@ -1,3 +1,13 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.ps1"
+  - "**/*.sh"
+---
+
 # New Production File Absent From Its Package Inventory
 
 **When this applies:** Any Write that creates a new production code file (`.py`, `.mjs`, `.js`, `.ts`, `.ps1`, `.sh`) in a directory whose sibling `README.md` or `CLAUDE.md` already names two or more of the directory's files in backticks, or in a skill's `scripts/` subdirectory whose parent `SKILL.md` Layout table already names two or more of those scripts.

package/rules/paired-test-coverage.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.py"
+---
+
 # Public-Function Paired-Test Coverage
 
 **When this applies:** Either side of a paired module/test pair, so the check fires whichever file the write touches:

package/rules/plain-illustrative-docstrings.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.py"
+---
+
 # Plain, Illustrative Docstrings
 
 **When this applies:** Any Write or Edit to a public function, method, class, or module docstring whose narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — says what the code is for or how it behaves. The standard governs the prose a reader meets first, not the structured `Args:` / `Returns:` entries below it.
@@ -14,6 +19,39 @@ Two shapes break the standard. Hold the prose clear of both:
 - **No machinery nouns stacked into a wall.** A sentence that chains abstract machinery terms (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`) names parts without painting a scene. Name what the reader sees and why it matters.
 - **No defining by negation.** Prose that explains a thing by what it is not (`the non-promoter-specific machinery`) leaves the reader without a picture. Say what the thing is.
 
+## Shape: a summary line, then a diagram
+
+The clearest way to be illustrative is to show a worked example, not describe one. A docstring that lands well reads in four parts:
+
+1. **One summary line** that says what the code does.
+2. **A diagram block** that carries the explanation by sight — a reStructuredText literal block (a line ending in `::`, then an indented example) or a doctest (`>>>`). Give the concrete input, mark the outcome, and add `ok:` / `flag:` contrast lines where a pass-and-fail pair makes the point. Keep the diagram clear of a bare number or an ALL-CAPS `NAME = value` line, which read as a magic value or a stray constant to a line-based lint pass.
+3. **A couple of short narrative lines** after the block — two or three at most.
+4. **The Google `Args:` / `Returns:` sections.**
+
+Keep the wording neutral in the diagram and the prose: two names "contradict" or "clash", two names "agree". Skip words that pass judgment.
+
+Canonical example:
+
+```
+Flag a boolean assignment whose target and callee assert opposite polarity.
+
+::
+
+    is_inside_allowed = _point_hits_any_forbidden(...)
+             ^^^^^^^                    ^^^^^^^^^
+             allowed         vs.        forbidden      ⚠ the two names clash
+    ok:   is_inside_allowed = _point_inside_allowed_region(...)
+    flag: is_inside_allowed = _point_hits_any_forbidden(...)
+
+The target token and the callee token contradict each other, so the reader
+cannot tell which name states the truth. Rename the callee to a neutral form
+the two names agree on at every call site.
+```
+
+The live version of this docstring sits on `check_polarity_name_contradiction` in `packages/claude-dev-env/hooks/blocking/code_rules_naming_collection.py`.
+
+A short narrative with no diagram is fine when a couple of plain sentences carry the whole picture. The diagram earns its place once the explanation grows past what two or three lines hold — the moment a wall of prose starts to form.
+
 ## What to check before you write the docstring
 
 Read the narrative back as a stranger would:
@@ -48,7 +86,8 @@ one — and you're debugging blind.
 
 Two surfaces carry this standard:
 
-- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark.
+- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
+- **Hook (the prose-wall backstop).** `check_docstring_prose_wall_without_illustration` in the same module flags a narrative that runs more than six prose lines with no diagram block. It marks the wall so the writer shows the behavior with a `::` example or a doctest and trims the prose to a few short lines. It cannot judge whether the diagram illustrates well; that stays with the audit lane.
 - **Audit (the judgment lane).** Category O sub-bucket O9 in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the hook cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.
 
 ## Why

package/rules/verify-before-asking.md

@@ -22,6 +22,13 @@ Before writing any AskUserQuestion or asking a clarifying question in chat, eval
 
 Only after confirming the answer cannot be obtained through any available tool, ask the user.
 
+## Prior-session facts expire
+
+A path, port, branch name, or config value you recall from an earlier session counts as unanswered until a tool re-checks it this session. Memory records what was true when it was written; the file may have moved, the port may be down, the branch may have merged. Treat every recalled fact as a claim to re-ground, not an answer to reuse.
+
+- When a tool can settle it, re-check in silence and act on the fresh result — no question to the user.
+- When no tool can settle it and the user has a stake in the answer, ask through `AskUserQuestion` (see [`confirm-implementation-forks`](confirm-implementation-forks.md)).
+
 ## Questions That Belong to the User
 
 Reserve user questions for: