claude-dev-env 1.83.0 → 1.85.0

package/hooks/hooks_constants/blocking_check_limits.py

@@ -99,6 +99,7 @@ ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES: dict[str, tuple[str, ...]] = {
 MAX_DOCSTRING_STEP_DISPATCH_ISSUES: int = 5
 MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK: int = 2
 MINIMUM_TOKENS_FOR_DISPATCH_CALLEE: int = 2
+MINIMUM_RANGE_ARGS_FOR_SPAN: int = 2
 MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES: int = 3
 MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES: int = 5
 SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT: int = 1
@@ -218,6 +219,9 @@ DOCSTRING_RUNON_SENTENCE_WORD_LIMIT: int = 30
 MAX_DOCSTRING_RUNON_SENTENCE_ISSUES: int = 5
 ALL_DOCSTRING_RUNON_JOINER_MARKERS: tuple[str, ...] = ("—", " -- ", ";")
 DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN: re.Pattern[str] = re.compile(r"(?<=[.!?])\s+")
+DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT: int = 6
+DOCSTRING_NARRATIVE_LINE_JOIN_SEPARATOR: str = " "
+MAX_DOCSTRING_PROSE_WALL_ISSUES: int = 5
 
 ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
     "no consumer reads",

package/hooks/hooks_constants/code_rules_path_utils_constants.py

@@ -22,8 +22,8 @@ ALL_CONFIG_DIRECTORY_NAMES = frozenset(
         "pr_converge_skill_constants",
         "pr_converge_scripts_constants",
         "bugteam_scripts_constants",
-        "doc_gist_scripts_constants",
         "implement_scripts_constants",
+        "log_audit_constants",
         "dev_env_scripts_constants",
     }
 )

package/hooks/hooks_constants/duplicate_rmtree_helper_blocker_constants.py

@@ -19,7 +19,6 @@ ALL_EXEMPT_PATH_FRAGMENTS: tuple[str, ...] = (
     "windows_safe_rmtree.py",
     "windows_filesystem.py",
     "session_env_cleanup.py",
-    "_md_to_html_blocker_test_support.py",
     "teardown_worktrees.py",
 )
 

package/hooks/hooks_constants/post_tool_use_dispatcher_constants.py

@@ -62,9 +62,4 @@ ALL_POST_HOSTED_HOOK_ENTRIES: tuple[PostHostedHookEntry, ...] = (
         script_relative_path="workflow/auto_formatter.py",
         is_blocking=False,
     ),
-    PostHostedHookEntry(
-        script_relative_path="workflow/doc_gist_auto_publish.py",
-        extra_argument_relative_paths=(PLUGIN_ROOT_PLACEHOLDER,),
-        is_blocking=False,
-    ),
 )

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.83.0",
+    "version": "1.85.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -33,7 +33,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `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 |

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

@@ -30,7 +30,7 @@ Read the body and the docstring side by side:
 - **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.
-- **Cardinal-count enumerations.** A docstring that states a count of an outcome family (`the four outcome branches`) and lists those members names every member of that family the module references. When the module imports and exercises a fifth `OUTCOME_*` constant the summary leaves out, the count and the list both under-describe the code. The `check_docstring_cardinal_count_matches_constant_family` gate blocks this drift — a cardinal-count docstring that names two or more members of a referenced `UPPER_SNAKE` constant family, leaves at least one referenced member out, and states a count below the family size — at Write/Edit time, on test modules as well as production modules.
+- **Cardinal-count enumerations.** A docstring that states a count of an outcome family (`the four outcome branches`) and lists those members names every member of that family the module references. When the module imports and exercises a fifth `OUTCOME_*` constant the summary leaves out, the count and the list both under-describe the code. The `check_docstring_cardinal_count_matches_constant_family` gate blocks this drift — a cardinal-count docstring that names two or more members of a referenced `UPPER_SNAKE` constant family, leaves at least one referenced member out, and states a count that differs from the family size (a count above it and one below it both trip) — at Write/Edit time, on test modules as well as production modules.
 - **Raises-clause reachability for `LargeZipFile`.** A `Raises:` clause that names `zipfile.LargeZipFile` matches a writer the body opens with ZIP64 forbidden. `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False; a function that opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` at its default of True allows ZIP64 and never raises it, so the clause documents an unreachable exception. Drop the entry, or pass `allowZip64=False` when forbidding ZIP64 is the goal. The `check_docstring_raises_unraisable_largezipfile` gate blocks the default-ZIP64-writer form of this drift at Write/Edit time; a writer that forbids ZIP64 on any open, a read-only open, and a function that opens no writer are all left alone.
 - **Module summary scope versus data-schema constants.** A module whose one-line docstring scopes its contents to user-facing text (`User-facing strings: CLI flag names, help text, and log messages`) names every category of constant the body holds. When the body also defines serialization field keys (`JSONL_FIELD_*`), run-metadata schema keys (`RUN_METADATA_CLI_ARG_KEY_*`), or runtime config (`STDOUT_ENCODING`, `MAIN_LOGGING_FORMAT_STRING`), the strings-only summary under-describes the module — the module-responsibility drift the repo flags. Broaden the summary to name the data-schema keys and runtime config. The `check_module_docstring_scope_omits_data_schema_constants` gate blocks this drift at Write/Edit time, and fires only when the summary claims a user-facing-text scope and names no data-schema or runtime-config category, so a summary that already names `field keys`, `schema`, or `runtime config` passes.
 - **Field meaning: run mode versus per record.** A dataclass or `TypedDict` field documented in the class `Attributes:` block states what the field means for one record. When the code sets that field the same way for every record (a run-mode flag such as `is_dry_run = not is_execute` at each write site), the description states the run-mode meaning, not a per-record outcome. A field named `is_dry_run` documented as `True when no STP was written` reads as a per-record write result, but the value tracks the run mode, so a record that writes no file during an execute run still stores `False`. State the run-mode meaning the assignment gives the field. The `check_docstring_field_runmode_outcome` gate blocks the single-file shape of this drift at Write/Edit time — an `Attributes:` entry for a run-mode flag field (a name carrying `dry_run`) whose description carries a per-record write-outcome phrase and no run-mode phrase. The assignment that sets the field sits in another module, out of reach of that single-file gate, so any shape the gate cannot key on stays an O6 audit-lane judgment finding.

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

@@ -22,7 +22,7 @@ The `env_var_table_code_drift_blocker.py` hook runs on every Write, Edit, and Mu
 3. Resolves the named code file under the repository root (the nearest `.git`-bearing ancestor of the markdown file) and reads its source.
 4. Blocks the write when the file resolves yet its source never references the variable name. For an Edit, drift the file already held on an untouched row is excluded, so only drift the edit introduces is reported.
 
-The check stays quiet for a row whose code file resolves nowhere under the repository root (it cannot prove the drift), a row whose second cell holds no code-file path, a table row inside a fenced code block, and any test file.
+The check stays quiet for a row whose code file resolves nowhere under the repository root (it cannot prove the drift), a row whose second cell holds no code-file path, and a table row inside a fenced code block.
 
 ## Why this is a hook, not a lint pass
 

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

@@ -10,7 +10,7 @@ paths:
 
 # 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.
+**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, in a directory whose own `SKILL.md` names two or more of the directory's files, or in a skill's `scripts/` subdirectory whose parent `SKILL.md` Layout table already names two or more of those scripts.
 
 ## Rule
 

package/rules/paired-test-coverage.md

@@ -23,7 +23,7 @@ Two complementary checks in `code_rules_paired_test.py` (both dispatched from `c
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 
 1. The target is production code — not a test module, hook infrastructure, config module, migration, workflow registry, or `__init__.py`.
-2. A stem-matched test file (`test_<stem>.py` or `<stem>_test.py`) exists for the module.
+2. A stem-matched test file exists for the module — `test_<stem>.py` or `<stem>_test.py` beside the module, or `test_<stem>.py` under an ancestor `tests/` directory.
 3. That suite already exercises the module — referencing at least one public function the module defines, or referencing one of its private (underscore-prefixed) helper functions by name — the signature of a maintained per-module suite rather than a placeholder or unrelated test file.
 4. The public function is referenced by no test file in the directory that holds the stem-matched test.
 

package/rules/plain-illustrative-docstrings.md

@@ -19,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:
@@ -53,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/skills/CLAUDE.md

@@ -35,6 +35,11 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `pr-consistency-audit` — cross-file consistency check on a PR diff
 - `copilot-review` — requests and polls a GitHub Copilot review
 - `findbugs` / `fixbugs` — find bugs then fix them in separate passes
+- `reviewer-gates` — availability gates for external reviewers (opt-out parse, Copilot quota, Bugbot trigger/detect)
+- `pr-scope-resolve` — one resolution ladder for a PR-loop skill's audit/fix target
+- `pr-fix-protocol` — fix, reply, and resolve reviewer findings; the unresolved-thread sweep
+- `post-audit-findings` — publishes an audit pass as one GitHub PR review
+- `pr-loop-lifecycle` — opens and closes a PR-loop run (grant, teardown, PR description, revoke, report)
 - `code` — strict-mode code generation session
 
 **Research and discovery**
@@ -62,5 +67,5 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `pre-compact` — compact-safe session handoff
 - `qbug` — required baseline PR audit; one clean-coder subagent loops audit → fix → commit → push until clean or stuck
 - `skill-builder` — complete skill-building lifecycle
-- `doc-gist` — uploads an HTML file as a secret gist
 - `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings
+- `log-audit` — background agent that audits this repo's own logs for recurring errors and timing regressions and files grouped fixes

package/skills/_shared/pr-loop/CLAUDE.md

@@ -21,6 +21,7 @@ Shared infrastructure for the PR audit-fix loop used by `bugteam` and `pr-conver
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_handoff.py` | Writes durable resume-handoff files under `~/.claude/runtime/pr-loop/<run-name>/` at each converge checkpoint. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
 | `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_xml_utils.py` | XML serialization helpers. |

package/skills/_shared/pr-loop/scripts/CLAUDE.md

@@ -13,6 +13,7 @@ Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr
 | `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
 | `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
 | `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
+| `write_handoff.py` | Writes durable resume-handoff files under the run's `~/.claude/runtime/pr-loop` directory at each converge checkpoint. |
 | `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
 | `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
 | `_xml_utils.py` | XML serialization helpers for outcome files. |

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/CLAUDE.md

@@ -9,6 +9,7 @@ Python package of named constants for the `pr-loop` shared scripts. All constant
 | `__init__.py` | Package marker. |
 | `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, fix status values, audit constraint texts, audit category entries, fix execution steps, and fix constraint texts. |
 | `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
+| `handoff_constants.py` | Filename, path-segment, and template constants for the durable handoff writer. |
 
 ## Usage
 

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/handoff_constants.py

@@ -0,0 +1,45 @@
+"""Filename, path-segment, and template constants for the durable handoff writer.
+
+Consumed by `write_handoff.py`, which writes each pr-loop run's resume-handoff
+files under `~/.claude/runtime/pr-loop/<run-name>/`.
+"""
+
+ALL_HANDOFF_DIR_SEGMENTS = (".claude", "runtime", "pr-loop")
+HANDOFF_JSON_FILENAME = "handoff.json"
+HANDOFF_MARKDOWN_FILENAME = "HANDOFF.md"
+STATE_COPY_FILENAME = "state-copy.json"
+ATOMIC_STAGING_SUFFIX = ".tmp"
+HANDOFF_JSON_INDENT = 2
+COMPLETED_STEPS_SEPARATOR = ","
+STEP_LINE_SEPARATOR = "\n"
+
+NO_STATE_SNAPSHOT_LINE = (
+    "No state snapshot was captured. Rebuild loop state from the PR before resuming."
+)
+DEFAULT_NEXT_STEP_LINE = "Continue from the resume command above."
+NO_STEPS_DONE_LINE = "- (none recorded yet)"
+
+HANDOFF_MARKDOWN_TEMPLATE = """# Resume handoff — PR {pr_number} ({head_ref})
+
+Goal: drive PR {pr_number} to convergence. This run stopped at phase `{phase}`.
+
+## Resume command
+
+Run this exactly:
+
+```
+{resume_command}
+```
+
+## State file to trust
+
+{state_line}
+
+## Steps already done
+
+{steps_block}
+
+## Next step
+
+{next_step}
+"""