claude-dev-env 1.82.0 → 1.83.0

package/hooks/hooks_constants/blocking_check_limits.py

@@ -28,7 +28,20 @@ MAX_THIN_WRAPPER_ISSUES: int = 1
 MAX_ZERO_PAYLOAD_ALIAS_ISSUES: int = 3
 MAX_LOGGING_FSTRING_ISSUES: int = 3
 MAX_LOGGING_PRINTF_TOKEN_ISSUES: int = 3
+MAX_LOGGING_ADJACENT_LITERAL_ISSUES: int = 3
+MAX_CONFIG_DUPLICATE_PATH_ANCHOR_ISSUES: int = 3
 MAX_WINDOWS_API_NONE_ISSUES: int = 3
+MAX_NAIVE_DATETIME_ISSUES: int = 3
+DATETIME_CLASS_ATTRIBUTE_NAME: str = "datetime"
+NAIVE_DATETIME_TIMEZONE_KEYWORD: str = "tz"
+NAIVE_DATETIME_UTCNOW_CONSTRUCTOR: str = "utcnow"
+NAIVE_DATETIME_UTCFROMTIMESTAMP_CONSTRUCTOR: str = "utcfromtimestamp"
+NAIVE_DATETIME_FROMTIMESTAMP_CONSTRUCTOR: str = "fromtimestamp"
+FROMTIMESTAMP_POSITIONAL_TIMEZONE_ARGUMENT_COUNT: int = 2
+ALL_ALWAYS_NAIVE_DATETIME_CONSTRUCTORS: tuple[str, ...] = (
+    NAIVE_DATETIME_UTCNOW_CONSTRUCTOR,
+    NAIVE_DATETIME_UTCFROMTIMESTAMP_CONSTRUCTOR,
+)
 MAX_E2E_TEST_NAMING_ISSUES: int = 3
 MAX_IMPORT_BLOCK_SORT_ISSUES: int = 1
 IMPORT_BLOCK_SORT_RUFF_TIMEOUT_SECONDS: int = 15
@@ -48,6 +61,11 @@ ALL_IMPORT_BLOCK_SORT_RUFF_COMMAND_PREFIX: tuple[str, ...] = (
 )
 MAX_JS_RESUME_TASK_ENUMERATION_ISSUES: int = 5
 MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES: int = 5
+MAX_JS_SIBLING_RETURN_OBJECT_KEY_DRIFT_ISSUES: int = 5
+MINIMUM_SIBLING_RETURN_OBJECT_KEYS: int = 2
+SIBLING_RETURN_OBJECT_EXACT_MISSING_KEY_COUNT: int = 1
+SIBLING_RETURN_OBJECT_SINGLE_AGREED_MISSING_KEY_COUNT: int = 1
+MAX_JS_BARE_FLAG_RETURN_DIRECTIVE_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
@@ -59,6 +77,7 @@ 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
 MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER: int = 2
+MINIMUM_SIBLING_OCCURRENCES_FOR_SHARED_TOKEN: int = 2
 MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES: int = 5
 MINIMUM_TUPLE_MEMBERS_FOR_DOCSTRING_ENUMERATION: int = 2
 MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES: int = 5
@@ -290,6 +309,30 @@ ALL_TEST_INDICATING_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
     }
 )
 
+MAX_DOCSTRING_DELEGATION_ENUMERATION_ISSUES: int = 5
+MINIMUM_DELEGATION_ENUMERATION_ITEMS: int = 2
+NEIGHBOR_SCAN_FILE_LIMIT: int = 40
+POINTER_TO_DELEGATE_PATTERN: re.Pattern[str] = re.compile(
+    r"full doc(?:umentation)?\s+on\s+`{1,2}([A-Za-z_][A-Za-z0-9_]*)`{1,2}",
+    re.IGNORECASE,
+)
+TOKEN_WORD_PATTERN: re.Pattern[str] = re.compile(r"[A-Za-z][A-Za-z0-9]{2,}")
+ALL_DELEGATION_ENUMERATION_STOP_TOKENS: frozenset[str] = frozenset(
+    {
+        "the",
+        "and",
+        "then",
+        "edit",
+        "edits",
+        "apply",
+        "applies",
+        "run",
+        "runs",
+        "step",
+        "steps",
+    }
+)
+
 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, ...] = (

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -185,7 +185,18 @@ LOGGING_FSTRING_PATTERN = re.compile(
 LOGGING_PRINTF_TOKEN_PATTERN: re.Pattern[str] = re.compile(
     r"(?<!%)%[#0\- +]?[0-9.*]*[sdrixfgeEcoX](?![a-zA-Z])"
 )
+ADJACENT_STRING_LITERAL_PATTERN: re.Pattern[str] = re.compile(
+    r'(?<!["\'])[rRbBfFuU]{0,2}(?:"(?:[^"\\\n]|\\.)*"|\'(?:[^\'\\\n]|\\.)*\')'
+    r'\s*[rRbBfFuU]{0,2}(?:"(?:[^"\\\n]|\\.)*"|\'(?:[^\'\\\n]|\\.)*\')(?!["\'])'
+)
 MINIMUM_FORMAT_LOGGER_ARGUMENT_COUNT = 2
+ALL_LOGGING_CALL_METHOD_NAMES: frozenset[str] = frozenset(
+    {"debug", "info", "warning", "error", "critical", "exception"}
+)
+LOGGING_HELPER_FUNCTION_NAME_PATTERN: re.Pattern[str] = re.compile(
+    r"^log_(?:debug|info|warning|error|critical|exception)$"
+)
+LOGGING_RECEIVER_NAME_PATTERN: re.Pattern[str] = re.compile(r"^_?(?:logger|logging|log)$")
 SPAWN_AGENT_WITH_JSDOC_PATTERN: re.Pattern[str] = re.compile(
     r"/\*\*(?P<jsdoc>(?:(?!\*/).)*?)\*/\s*"
     r"(?:async\s+)?function\s+spawn(?P<role>\w+?)Agent\s*\(",
@@ -233,9 +244,39 @@ JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN: re.Pattern[str] = re.compile(
 RETURN_CALL_OPENING_PARENTHESIS_PATTERN: re.Pattern[str] = re.compile(
     r"\breturn\s+(?:await\s+)?(?P<callee>\w+)\s*\("
 )
+BARE_FLAG_CONTRACT_PATTERN: re.Pattern[str] = re.compile(
+    r"never a bare (?P<flag>\w+) flag", re.IGNORECASE
+)
+BARE_FLAG_RETURN_DIRECTIVE_PATTERN: re.Pattern[str] = re.compile(
+    r"\breturn\s+(?P<flag>\w+)\s*:\s*(?:true|false)\b", re.IGNORECASE
+)
 SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN: re.Pattern[str] = re.compile(
     r"(?<![A-Za-z0-9_])schema\s*:"
 )
+RETURN_OBJECT_LITERAL_OPENING_PATTERN: re.Pattern[str] = re.compile(r"\breturn\s*\{")
+ARROW_CONCISE_BODY_OBJECT_LITERAL_OPENING_PATTERN: re.Pattern[str] = re.compile(
+    r"=>\s*\(\s*\{"
+)
+JS_OBJECT_KEY_IDENTIFIER_PATTERN: re.Pattern[str] = re.compile(r"[A-Za-z_$][\w$]*")
+JS_OBJECT_METHOD_SHORTHAND_KEY_PATTERN: re.Pattern[str] = re.compile(
+    r"\A([A-Za-z_$][\w$]*)\s*\("
+)
+ALL_JAVASCRIPT_CONTROL_FLOW_BLOCK_KEYWORDS: frozenset[str] = frozenset(
+    {"if", "for", "await", "while", "switch", "catch", "with"}
+)
+ALL_JAVASCRIPT_PARENTHESIS_FREE_BLOCK_KEYWORDS: frozenset[str] = frozenset(
+    {"else", "do", "try", "finally"}
+)
+ALL_JAVASCRIPT_BRACKET_OPENERS: frozenset[str] = frozenset({"(", "[", "{"})
+ALL_JAVASCRIPT_BRACKET_CLOSERS: frozenset[str] = frozenset({")", "]", "}"})
+ALL_JAVASCRIPT_IDENTIFIER_EXTRA_CHARACTERS: frozenset[str] = frozenset({"_", "$"})
+ALL_JAVASCRIPT_RETURN_TYPE_TERMINATORS: frozenset[str] = frozenset({"}", ">", "]"})
+JAVASCRIPT_ARROW_TOKEN_LENGTH: int = 2
+ALL_JAVASCRIPT_BARE_RETURN_TYPE_EXTRA_CHARACTERS: frozenset[str] = frozenset(
+    {"_", "$", ".", "|", "&", "?"}
+)
+JAVASCRIPT_OBJECT_SPREAD_PREFIX: str = "..."
+JAVASCRIPT_MODULE_SCOPE_SENTINEL: int = -1
 ALL_BUILTIN_DICT_METHOD_NAMES: frozenset[str] = frozenset({
     "get", "items", "keys", "values", "update", "pop",
     "setdefault", "copy", "clear",

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -105,6 +105,10 @@ ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
         applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
         native_module_name=STATE_DESCRIPTION_BLOCKER_MODULE_NAME,
     ),
+    HostedHookEntry(
+        script_relative_path="blocking/stale_comment_reference_blocker.py",
+        applicable_tool_names=frozenset({EDIT_TOOL_NAME}),
+    ),
     HostedHookEntry(
         script_relative_path="blocking/subprocess_budget_completeness.py",
         applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,

package/hooks/hooks_constants/reviewer_spawn_gate_constants.py

@@ -0,0 +1,41 @@
+"""Configuration constants for the reviewer_spawn_gate PreToolUse hook."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+BASH_TOOL_NAME: str = "Bash"
+
+GATE_SENTINEL_MARKER: str = "CLAUDE_REVIEWER_GATE=autoconverge"
+
+COPILOT_REVIEWER_TOKEN: str = "copilot"
+BUGBOT_REVIEWER_TOKEN: str = "bugbot"
+
+COPILOT_REVIEWER_LABEL: str = "GitHub Copilot"
+BUGBOT_REVIEWER_LABEL: str = "Cursor Bugbot"
+
+ALL_COPILOT_TRIGGER_MARKERS: tuple[str, ...] = (
+    "requested_reviewers",
+    "copilot-pull-request-reviewer[bot]",
+)
+
+BUGBOT_TRIGGER_SCRIPT_MARKER: str = "post_fix_reply.py"
+BUGBOT_RUN_BODY_PATTERN: re.Pattern[str] = re.compile(
+    r'--body\s+["\']bugbot run["\']', re.IGNORECASE
+)
+
+AVAILABILITY_SCRIPT_RELATIVE_PATH: Path = (
+    Path("_shared") / "pr-loop" / "scripts" / "reviewer_availability.py"
+)
+AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME: str = "REVIEWER_SPAWN_GATE_AVAILABILITY_SCRIPT_PATH"
+AVAILABILITY_SCRIPT_TIMEOUT_SECONDS: int = 15
+AVAILABILITY_REVIEWER_FLAG: str = "--reviewer"
+AVAILABILITY_DOWN_EXIT_CODE: int = 3
+
+DENY_REASON_TEMPLATE: str = (
+    "BLOCKED [reviewer-spawn-gate]: {reviewer_label} is down or out of quota "
+    "this run. Skip requesting {reviewer_label} on this trigger — "
+    "autoconverge requests it again once the availability check reports it "
+    "back.\n\nAvailability check output: {availability_detail}"
+)

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/package.json

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

package/rules/CLAUDE.md

@@ -28,6 +28,7 @@ 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 |
@@ -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.

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:

package/rules/verify-runtime-state.md

@@ -0,0 +1,40 @@
+# Verify Runtime State
+
+**When this applies:** Before stating that a component is fine, healthy, not at fault, or working — during debugging, triage, or any judgment about whether something runs.
+
+## Rule
+
+A verdict that a component is fine or not the cause rests on live evidence gathered this session: a process list, a port probe, a log tail, an HTTP status code, or a fresh repro. Reading the code, recalling how the component behaved earlier, or trusting a prior session's finding does not settle whether it runs right now. Code shows what should happen; only a live probe shows what does.
+
+Gather the probe before you write the verdict. When the probe contradicts the code (the code looks right but the port refuses the connection), report the live result and treat the component as suspect.
+
+## Grounding checklist
+
+Before stating a runtime claim, gather the matching live signal:
+
+| Claim | Grounding probe |
+|---|---|
+| The service is healthy | Hit its health endpoint and read the status code. |
+| The config is in effect | Print the loaded config at runtime and read the value. |
+| The server is up | Probe the port; a refused connection means it is down. |
+| The process is running | List processes and match the name or PID. |
+| The change took effect | Drive the flow and watch the new behavior. |
+| The dependency is reachable | Send one real request and read the response. |
+
+Only after a live signal backs the claim do you state it.
+
+## Examples
+
+**Wrong:** "The search server code looks correct, so it is not the problem."
+**Right:** Probe port 54321; report "connection refused — the server is down."
+
+**Wrong:** "This function handles the retry, so the request must be going through."
+**Right:** Tail the request log and confirm the retry fired, or report that no retry line appears.
+
+**Wrong:** "The config sets the timeout to 30 seconds, so the timeout is fine."
+**Right:** Print the loaded config at runtime and report the value the process actually holds.
+
+## Relationship to other rules
+
+- **`verify-before-asking`** answers questions with a tool before asking the user. This rule extends that to runtime verdicts: gather the live probe before you conclude, not just before you ask.
+- **`long-horizon-autonomy`** requires every progress claim to rest on a tool result from this session. A runtime verdict is a progress claim; this rule names the probes that back it.

package/rules/windows-filesystem-safe.md

@@ -1,3 +1,11 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.js"
+  - "**/*.ts"
+---
+
 # Windows Filesystem Safety
 
 Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` files (e.g. `.git/objects/pack/`) raise `PermissionError`, the flag swallows it, and the tree silently stays on disk. Use an `onexc` (Python >= 3.12) / `onerror` handler that runs `os.chmod(target_path, stat.S_IWRITE)` then retries the removal function the failure interrupted.

package/rules/workers-done-before-complete.md

@@ -0,0 +1,33 @@
+# Workers Done Before Complete
+
+**When this applies:** Before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
+
+## Rule
+
+A task reaches `completed` only when two things hold: every worker it spawned has finished, and each worker's result is merged into run state — `state.json`, `pr-converge-state.json`, the task list, or whatever record the task keeps. A worker that still runs, or one that finished but whose output never landed in run state, leaves the task open.
+
+List the live workers before you mark the task complete. When a worker is dead or hung, that is a finding to record and report, not a result to drop in silence. A step that waits on workers ends its turn `in_progress` with a wakeup scheduled, so the run picks the workers back up rather than closing the task without them.
+
+## Checklist before marking complete
+
+| Check | Action |
+|---|---|
+| Are any spawned workers still running? | List them; if yes, stay `in_progress` and schedule a wakeup. |
+| Did every finished worker return a result? | Read each result; a dead or hung worker is a finding to report. |
+| Is each result merged into run state? | Write it to `state.json` / the task list before closing. |
+| Does the task's own goal now hold? | Confirm against the merged state, not a worker's self-report. |
+
+Mark `completed` only when every row passes.
+
+## Examples
+
+**Wrong:** Marking the audit task complete while two bugteam workers still run in the background.
+**Right:** List the workers, see two still running, keep the task `in_progress`, and schedule a wakeup to collect them.
+
+**Wrong:** A worker crashes; the task closes as complete because the other workers finished.
+**Right:** Record the crashed worker as a finding, report it, and hold the task open until its work is covered.
+
+## Relationship to other rules
+
+- **`long-horizon-autonomy`** covers acting on what you have and not ending a turn on a promise. This rule names the specific completion gate: workers finished and their results merged.
+- **`skills/pr-converge/reference/state-schema.md`** defines the run-state records this rule requires a worker's result to land in before the task closes.

package/rules/workflow-substitution-slots.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "**/*.workflow.js"
+---
+
 # Workflow Substitution Slot Rule
 
 In a `.workflow.js` agent-prompt template, every per-call or per-iteration value an agent must fill in is marked with the angle-bracket convention — `<plate.svg>`, `<object.svg>`, `<glow_hex>`, `cand_<i>`. A bare token such as `cand_i` reads as a fixed literal, so an agent can create one literal directory named `cand_i` and overwrite it across every iteration of a loop, collapsing an N-iteration gate into a single run.

package/skills/CLAUDE.md

@@ -42,7 +42,7 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `research-mode` — activates anti-hallucination discipline for a session
 - `recall` — retrieves facts from memory files
 - `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
-- `everything-search` — file-system search via the Everything MCP tool
+- `everything-search` — file-system search via the Everything `es.exe` CLI
 - `caveman` — trims noise from a draft artifact
 
 **Session and workflow management**