claude-dev-env 2.0.1 → 2.0.2

package/agents/clean-coder.md

@@ -2,7 +2,7 @@
 name: clean-coder
 description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes CODE_RULES.md and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
 model: opus
-tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill
+tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill, SendMessage
 color: green
 ---
 
@@ -389,6 +389,36 @@ BEFORE writing:
 [12] One abstraction level throughout?
 ```
 
+## Pre-Check Loop — Validate Candidate Content Before Each Write
+
+The write gate reports every violation in one denial, so a blocked write is a poor place to find a rule. Run the checker on the candidate content first, read the verdict, fix each line, and re-run until the verdict is clean. Then call Write or Edit, and the write lands on the first try.
+
+### The two local surfaces
+
+- **`code_rules_enforcer.py --check <candidate> [--as <target>]`** — the full CODE_RULES verdict on one complete candidate file. Stage the candidate at any path and point `--as` at the real destination. The `--as` target drives every path-based decision (test-file detection, `config/` exemption, hook-infrastructure exemption), so a candidate staged in a temp folder is judged as if it sat at its destination. Exit `0` is clean or an exempt target; `1` is one or more violations, each on its own line, or an unreadable candidate; `2` is a malformed flag sequence.
+- **`run_all_validators.py`** — the validator suite over the git-changed files: Ruff, Mypy, type safety, magic values, abbreviations, and more. `--pre-tool-use` runs the same suite as a gate on one proposed write from stdin. `--health` reports whether the suite runs.
+
+Point `--as` at the file's real production path. When `--as` names an exempt path, the check returns `0` for a candidate that carries violations, so a wrong target hides the verdict you want.
+
+### The loop
+
+1. Build the full candidate content.
+2. Stage it at a temp path with the Write tool or the PowerShell tool.
+3. Run `code_rules_enforcer.py --check <staged path> --as <real destination>`.
+4. Read every reported line and fix each one in the candidate.
+5. Re-run step 3. A fix can raise a fresh violation: a magic number pulled to a module constant needs the `ALL_` collection prefix, and that rename can leave the source constant with no reader; a long function split to meet the length target can push the file past the length advisory. Loop steps 3 through 5 until the verdict is clean.
+6. Call Write or Edit with the clean content.
+
+Re-running the checker after each fix catches the rework a single pass misses, so the write clears the gate one time.
+
+### Windows shell shape
+
+Create every multi-line script with the PowerShell tool or the Write tool. A bash heredoc on Windows strips backslashes from paths and garbles multi-line Python, so a heredoc-built script fails in ways its source text hides. For a wait-for-condition step, drive a Monitor until-loop; a `sleep && tail` poll chain blocks the turn and misses the moment the condition flips.
+
+### Mining session transcripts
+
+When reading transcripts under the user projects directory, pass explicit file paths to the reader, or search through Python or `Select-String`. A `.gitignore` holding `*` in that tree makes ripgrep and Grep directory recursion return zero matches with no error, so a recursive pattern reads as a clean miss even when files match.
+
 ## Constants Protocol
 
 Decision tree before writing any constant:

package/audit-rubrics/prompts/category-e-dead-code.md

@@ -66,7 +66,7 @@ Inline the artifact under this section using the section types defined in the ch
 **E8. Stub / placeholder code without TODO**
 - Distinguish real-behavior `pass` / `continue` / empty-handler bodies (intentional swallowing of expected exceptions, no-op branches that exist to satisfy a contract) from scaffolding stubs.
 - Real-behavior bodies do NOT require a TODO; the audit must state the rationale (e.g., "rmdir race with concurrent writer is intentionally swallowed").
-- Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) without a `# TODO` comment ARE Category E findings under the project's "Document Temporary Code" rule.
+- Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) without a `# TODO` comment ARE Category E findings under the project's `CODE_RULES.md` → "COMMENT PRESERVATION" rule.
 - Adversarial probes for proof-of-absence: (a) any empty brace block in PowerShell / TypeScript / Go (`{ }` with no statements)? (b) any function whose entire body is `pass` / `return` / `return None`? (c) any branch that exits cleanly only because the surrounding loop is no-op for an empty input — is the no-op intentional or a placeholder?
 
 **E9. Constants-module exports with no importer**
@@ -165,7 +165,7 @@ ID prefix: `find`.
 - `sweep_empty_dirs.py` line 28: the second `except OSError: continue` similarly is intended behavior (skip the directory whose ctime is unreadable), not a stub.
 - No `...` literal anywhere in the four files.
 - No `raise NotImplementedError` anywhere.
-- No `# TODO` markers in the diff — the project's own rule (`code-standards.md` → "Document Temporary Code") requires TODOs only for scaffolding/placeholder code. The two `pass`/`continue` bodies above are production behavior, not scaffolding.
+- No `# TODO` markers in the diff — the project's own rule (`CODE_RULES.md` → "COMMENT PRESERVATION") requires TODOs only for scaffolding/placeholder code. The two `pass`/`continue` bodies above are production behavior, not scaffolding.
 - Adversarial probes for proof-of-absence: (a) does the PowerShell script have an empty `else { }` or empty branch body? — scan lines 14-71 for any `{ }` with no statements between the braces. (b) does any function body consist of a single `pass` or `return` with no work done? — every function body in this PR performs at least one statement. (c) does the `Status` branch (lines 14-31) exit cleanly even when `$task.Triggers` is empty? — the `foreach` loop at line 26 is a no-op for an empty collection, which is correct behavior, not a stub.
 
 **E9. Constants-module exports with no importer**

package/bin/install.test.mjs

@@ -803,13 +803,13 @@ test('managedHookScriptRelativePathsFromSourceRoots unions managed scripts acros
             hooks: { Stop: [{ matcher: '', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py' }] }] },
         });
         writeHooksJsonAtRoot(dependencyRoot, {
-            hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pwsh_enforcer.py' }] }] },
+            hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/example_hook.py' }] }] },
         });
 
         const relativePaths = managedHookScriptRelativePathsFromSourceRoots([builtinRoot, dependencyRoot]);
 
         assert.ok(relativePaths.has('blocking/code_rules_enforcer.py'));
-        assert.ok(relativePaths.has('blocking/pwsh_enforcer.py'));
+        assert.ok(relativePaths.has('blocking/example_hook.py'));
         for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
             assert.ok(relativePaths.has(foldedPath), `folded hook ${foldedPath} must always be in the managed set`);
         }

package/docs/CLAUDE.md

@@ -14,8 +14,9 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 | `PR_DESCRIPTION_GUIDE.md` | Authoritative reference for the `pr-description-writer` agent; PR body shapes derived from a 120-PR Anthropic corpus |
 | `DJANGO_PATTERNS.md` | Django-specific coding patterns |
 | `REACT_PATTERNS.md` | React-specific coding patterns |
-| `emotion-informed-prompt-design.md` | Guidance for emotionally-aware prompt authoring |
-| `agents-md-alignment-plan.md` | Alignment between `AGENTS.md` review-tool rules and the local hook enforcement layer |
+| `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
+| `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
+| `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
 
 ## Subdirectory
 
@@ -25,4 +26,6 @@ Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. T
 
 ## Load pattern
 
-Rules reference these docs with `@~/.claude/docs/<file>.md` to pull them into context only when needed, rather than loading every doc on every session start.
+A rule points to a doc with the path wrapped in backticks, such as `@~/.claude/docs/<file>.md`. The backticks make it a plain pointer: Claude Code reads the doc only when a rule, skill, or agent opens it, so the doc stays out of session-start context. The same path without backticks expands into context at launch when it sits in a file that loads at session start.
+
+The `InstructionsLoaded` hook confirms this: a bare `@`-import fires an `include` load event; a backtick-wrapped path fires none.

package/docs/CODE_RULES.md

@@ -8,6 +8,8 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 **Keep existing comments in place.** Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook treats the two directions differently: adding a new inline comment blocks the edit, while removing an existing comment prints a stderr advisory and lets the edit through.
 
+Scaffolding and placeholder code carry a `TODO:` comment naming the permanent implementation and why the code is temporary — the documented exception to the no-new-comments rule.
+
 ---
 
 ## CORE PRINCIPLES
@@ -16,6 +18,7 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 - **Centralized configuration** — every constant lives in ONE place (`config/`).
 - **Reuse before create** — search first, import second, create last.
 - **Encapsulation enables cleaner naming** — `isMaxLevel(level)` > `level >= MAXIMUM_LEVEL`.
+- **Construction logic lives in the model** — path/URL building, formatting, and transformations belong on the model or service that owns the data; a string pattern built at two or more call sites moves to a method there.
 
 ---
 
@@ -37,7 +40,7 @@ Before writing ANY constant: search `config/` for the exact value → semantic m
 
 ## 5. NO ABBREVIATIONS
 
-Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` for exception. Naming patterns: loop vars `each_*`; booleans `is_/has_/should_/can_/was_/did_`; collections `all_*`; maps `X_by_Y`; preposition params (`from_path=`, `to=`, `into=`). Banned names: `result`, `data`, `output`, `response`, `value`, `item`, `temp`. Banned prefixes: `handle`, `process`, `manage`, `do`.
+Full words only (`context`, not `ctx`). Exceptions: `i`/`j`/`k` in loops, `e` for exception. Naming patterns: loop vars `each_*`; booleans `is_/has_/should_/can_/was_/did_`; collections `all_*`; maps `X_by_Y`; preposition params (`from_path=`, `to=`, `into=`). Banned names: `result`, `data`, `output`, `response`, `value`, `item`, `temp`. Banned prefixes: `handle`, `process`, `manage`, `do`. Name a component for what it IS — `Overlay`, `Validator`, `InvoicePreview`.
 
 ---
 
@@ -55,6 +58,7 @@ Advisory only, never blocking: soft advisory at >= 400 lines, strong nudge at >=
 
 **Simple > Clever. Functions > Classes. Concrete > Abstract.**
 Never: ABC for single impl, DI frameworks, factory for single type. Always: functions when no state, concrete classes, simple imports.
+Parameters follow YAGNI: add an optional parameter when a caller varies the value; when every call site passes the same value, make it required or inline the constant. Remove parameters no caller passes and no body reads.
 
 ## 7.5 SOLID PRINCIPLES
 

package/docs/agent-spawn-protocol.md

@@ -0,0 +1,39 @@
+# Agent Spawn Protocol
+
+Full protocol behind the always-on `rules/agent-spawn-protocol.md` kernel. It applies before any Agent or Task tool invocation — Explore, implementation, research, or team subagents.
+
+## Step 1: Context sufficiency check
+
+Before writing any agent prompt, confirm you can answer all of these:
+
+- What specific files, directories, or areas of the codebase are involved?
+- What constraints apply — patterns to follow, things to leave untouched, boundaries?
+- What does success look like — expected output, acceptance criteria?
+- Is the task unambiguous enough to delegate?
+
+When any answer is "I don't know", investigate first (read files, search code) or ask the user. Do not spawn with incomplete context.
+
+## Step 2: Craft the prompt with /prompt-generator
+
+Run the `/prompt-generator` skill to produce a structured prompt. Feed it:
+
+- The task description and goal
+- Target files and directories found in Step 1
+- Constraints and boundaries
+- Expected output format
+- Acceptance criteria
+
+The skill asks one to three clarifying questions when information is missing — this is the built-in context verification. Use the skill's output as the agent's `prompt` parameter.
+
+## Step 3: Spawn the agent
+
+Pass the structured prompt from Step 2 to the Agent or Task tool.
+
+## Why
+
+An agent that receives a vague prompt wastes tokens exploring in circles, produces code that misses constraints, and needs a second pass. A small investment in prompt quality through `/prompt-generator` saves a long agent failure. This holds for Explore agents, which waste context on unfocused searches, and for execution agents, which write wrong code.
+
+## Relationship to other rules
+
+- `conservative-action.md` gates acting when intent is ambiguous. This protocol extends that: an ambiguous task goes to investigation or a user question first, never straight to a subagent.
+- Project-specific rules or `~/.claude/CLAUDE.md` may decide whether to use subagents at all; this protocol governs how to craft the prompt once you delegate.

package/docs/nas-ssh-invocation.md

@@ -0,0 +1,23 @@
+# NAS SSH Invocation Policy
+
+Full detail behind the always-on `rules/nas-ssh-invocation.md` kernel. It applies to any `ssh`, `scp`, or `sftp` command against the NAS.
+
+## Why the Windows OpenSSH binary
+
+Git Bash's MSYS `ssh` reads `~/.ssh/id_ed25519` as world-readable through its ACL mapping, rejects the key as bad permissions, offers no key, and falls back to an interactive password prompt. In an unattended session no one answers that prompt, so the session hangs. The `System32/OpenSSH` binary authenticates the same key without a prompt.
+
+## The form to use
+
+```
+"/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 22 operator@nas.example.local "<cmd>"
+```
+
+`scp` and `sftp` take the matching `System32/OpenSSH` binary, `-o BatchMode=yes`, and the same port (`-P` for `scp`).
+
+The host, ssh user, and port come from the `CLAUDE_NAS_*` environment variables or `~/.claude/local-identity.json`; the committed examples show placeholders (`nas.example.local`, `operator`, `22`).
+
+`-o BatchMode=yes` is required, not optional: it turns a key-authentication failure into a loud non-zero exit rather than a silent password prompt, so an auth regression surfaces as an error you can read.
+
+## Enforcement
+
+`nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare `ssh`/`scp`/`sftp` command word aimed at the NAS host and points at the full-binary form. It also denies the full `System32/OpenSSH` binary to that host when the command omits `-o BatchMode=yes`. Commands to any other host, and commands that mention the address without an ssh-family command word, pass.

package/docs/worker-completion-gate.md

@@ -0,0 +1,33 @@
+# Worker Completion Gate
+
+Full detail behind the always-on `rules/workers-done-before-complete.md` kernel. It applies before marking any task `completed` when the task spawned workers — subagents, workflow agents, or background shells.
+
+## The gate
+
+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; when 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` or 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 gate names the specific completion condition: workers finished and their results merged.
+- `skills/pr-converge/reference/state-schema.md` defines the run-state records a worker's result lands in before the task closes.

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -74,6 +74,7 @@ from hooks_constants.dead_module_constant_constants import (  # noqa: E402
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
     DEAD_MODULE_CONSTANT_GUIDANCE,
+    DEAD_MODULE_CONSTANT_RETRY_GUIDANCE,
     DUNDER_ALL_NAME,
     DUNDER_INIT_FILENAME,
     GIT_DIRECTORY_NAME,
@@ -204,9 +205,11 @@ def _referenced_names_in_source(
     """Return every name a module references — imported, read, or re-exported.
 
     Collects imported binding names, ``from`` import member names, name
-    references, attribute roots, and (when ``collect_string_literals`` is set)
-    string literals, so a name listed in an ``__all__`` literal or named in a
-    string annotation counts as a reference. A module that fails to parse
+    references, both the root and the member name of each attribute access (so
+    ``module.CONSTANT`` counts ``CONSTANT`` as read), and (when
+    ``collect_string_literals`` is set) string literals, so a name listed in an
+    ``__all__`` literal or named in a string annotation counts as a reference. A
+    module that fails to parse
     contributes no names. With ``load_only`` set, only ``Load``-context names
     count, so a constant's own assignment target in the module being judged does
     not count as a reference to itself.
@@ -234,6 +237,8 @@ def _referenced_names_in_source(
             if load_only and not isinstance(each_node.ctx, ast.Load):
                 continue
             referenced_names.add(each_node.id)
+        elif isinstance(each_node, ast.Attribute):
+            referenced_names.add(each_node.attr)
         elif isinstance(each_node, ast.Import | ast.ImportFrom):
             for each_alias in each_node.names:
                 referenced_names.add(each_alias.asname or each_alias.name)
@@ -631,8 +636,9 @@ def check_dead_module_constants(
         if each_name in all_referenced_names:
             continue
         issues.append(
-            f"Line {each_line}: module-level constant {each_name!r}"
-            f" - {DEAD_MODULE_CONSTANT_GUIDANCE}"
+            f"Line {each_line}: module-level constant {each_name!r} in"
+            f" {written_path.name} - {DEAD_MODULE_CONSTANT_GUIDANCE}"
+            f" {DEAD_MODULE_CONSTANT_RETRY_GUIDANCE}"
         )
         if len(issues) >= MAX_DEAD_MODULE_CONSTANT_ISSUES:
             break

package/hooks/blocking/config/verified_commit_constants.py

@@ -131,7 +131,14 @@ CORRECTIVE_MESSAGE = (
     "and recorded baselines; when it finishes with a clean verdict the "
     "SubagentStop hook mints the verdict and this command will pass. Any "
     "file change after verification invalidates the verdict, so verify "
-    "last. Exempt automatically: docs/image files, pytest test files, and "
+    "last. The verdict binds to the exact surface content (every changed "
+    "and untracked file's bytes), not to a work-tree path, so a commit "
+    "from a different work tree passes only when its surface is "
+    "byte-identical; a work tree carrying any extra or later edit has a "
+    "surface no verdict covers. To land this change, run this command "
+    "from the work tree that holds the verified surface, or verify this "
+    "surface here. Exempt automatically: docs/image files, pytest test "
+    "files, and "
     "Python files whose docstring- and comment-stripped AST is unchanged "
     "(comment-only edits in non-Python files are not exempt)."
 )

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -448,3 +448,61 @@ def test_widened_scan_reads_each_file_at_most_once(
     assert not over_read_paths, (
         f"Widening must read each .py file at most once, got over-reads: {over_read_paths}"
     )
+
+
+def _build_settings_package(workflow_directory: Path, constants_body: str) -> Path:
+    constants_package = workflow_directory / "app_settings"
+    constants_package.mkdir(parents=True)
+    (constants_package / "__init__.py").write_text("", encoding="utf-8")
+    constants_path = constants_package / "app_settings_constants.py"
+    constants_path.write_text(constants_body, encoding="utf-8")
+    return constants_path
+
+
+def test_deny_once_records_intent_then_retry_passes_after_consumer(
+    neutral_root: Path,
+) -> None:
+    constants_body = 'PATH_ENV_NAME = "THEME_PATH"\n'
+    workflow_directory = neutral_root / "workflow"
+    constants_path = _build_settings_package(workflow_directory, constants_body)
+    first_issues = _check(constants_body, str(constants_path))
+    assert any("PATH_ENV_NAME" in each_issue for each_issue in first_issues), first_issues
+    assert any(
+        "app_settings_constants.py" in each_issue for each_issue in first_issues
+    ), f"Deny message must record the target constants module, got: {first_issues}"
+    assert any(
+        "re-issue this write" in each_issue for each_issue in first_issues
+    ), f"Deny message must instruct the retry escape, got: {first_issues}"
+    consumer_body = (
+        "from app_settings.app_settings_constants import PATH_ENV_NAME\n"
+        "\n"
+        "def resolve() -> str:\n"
+        "    return PATH_ENV_NAME\n"
+    )
+    (workflow_directory / "consumer_service.py").write_text(
+        consumer_body, encoding="utf-8"
+    )
+    retry_issues = _check(constants_body, str(constants_path))
+    assert retry_issues == [], (
+        f"Once the consumer is on disk the retry passes, got: {retry_issues}"
+    )
+
+
+def test_dead_constant_stays_denied_on_every_attempt(neutral_root: Path) -> None:
+    constants_body = 'PATH_ENV_NAME = "THEME_PATH"\n'
+    workflow_directory = neutral_root / "workflow"
+    constants_path = _build_settings_package(workflow_directory, constants_body)
+    (workflow_directory / "unrelated.py").write_text(
+        "def noop() -> int:\n    return 1\n", encoding="utf-8"
+    )
+    first_issues = _check(constants_body, str(constants_path))
+    second_issues = _check(constants_body, str(constants_path))
+    for each_attempt in (first_issues, second_issues):
+        assert any("PATH_ENV_NAME" in each_issue for each_issue in each_attempt), each_attempt
+        assert any(
+            "app_settings_constants.py" in each_issue for each_issue in each_attempt
+        ), f"Every deny attempt records the target module, got: {each_attempt}"
+        assert any(
+            "re-issue this write" in each_issue for each_issue in each_attempt
+        ), f"A dead constant stays denied with the retry escape, got: {each_attempt}"
+

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant_alias.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import stat
+import tempfile
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+import pytest
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location("code_rules_enforcer", ENFORCER_PATH)
+assert specification is not None and specification.loader is not None
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+CONSTANTS_BODY = 'MEDIUM_TERMINAL = "terminal"\nMEDIUM_CODE = "code"\nMEDIUM_TEXT = "text"\n'
+
+
+def _strip_read_only_and_retry(
+    removal_function: Callable[[str], object],
+    target_path: str,
+    _exc_info: BaseException,
+) -> None:
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+@pytest.fixture
+def neutral_root() -> Iterator[Path]:
+    """Yield a temp directory whose path carries no ``test_`` segment.
+
+    ::
+
+        tmp_path (pytest default)    -> embeds "test_..." in its name
+                                          -> is_test_file() misreads the path
+        mkdtemp(prefix="deadconst-") -> no "test_" segment  ->  reads as
+                                          a production path  ok
+
+    A ``.git`` marker is planted at the root so the cross-tree widening
+    resolves the repository root to this synthetic tree.
+    """
+    neutral_directory = Path(tempfile.mkdtemp(prefix="deadconst-")).resolve()
+    (neutral_directory / ".git").mkdir()
+    try:
+        yield neutral_directory
+    finally:
+        shutil.rmtree(neutral_directory, onexc=_strip_read_only_and_retry)
+
+
+def _check(source: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_module_constants(source, file_path)
+
+
+def _build_constants_package(
+    workflow_directory: Path,
+    constants_body: str,
+    consumer_body: str,
+) -> Path:
+    constants_package = workflow_directory / "report_constants"
+    constants_package.mkdir(parents=True)
+    (constants_package / "__init__.py").write_text("", encoding="utf-8")
+    constants_path = constants_package / "render_report_constants.py"
+    constants_path.write_text(constants_body, encoding="utf-8")
+    (workflow_directory / "render_report.py").write_text(consumer_body, encoding="utf-8")
+    return constants_path
+
+
+def _assert_alias_read_constants_live(issues: list[str]) -> None:
+    assert not any(
+        "MEDIUM_TERMINAL" in each_issue or "MEDIUM_CODE" in each_issue for each_issue in issues
+    ), f"A constant read as attribute of an imported module stays live, got: {issues}"
+    assert any("MEDIUM_TEXT" in each_issue for each_issue in issues), (
+        f"A constant read by no module must still be flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_constant_read_via_from_import_module_alias_attribute(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from report_constants import render_report_constants as constants\n"
+        "\n"
+        "def panel_class(medium: str) -> str:\n"
+        "    if medium == constants.MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    return 'code' if medium == constants.MEDIUM_CODE else 'other'\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", CONSTANTS_BODY, consumer_body
+    )
+    _assert_alias_read_constants_live(_check(CONSTANTS_BODY, str(constants_path)))
+
+
+def test_does_not_flag_constant_read_via_import_as_alias_attribute(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "import report_constants.render_report_constants as constants\n"
+        "\n"
+        "def label(medium: str) -> str:\n"
+        "    if medium == constants.MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    return 'code' if medium == constants.MEDIUM_CODE else 'other'\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", CONSTANTS_BODY, consumer_body
+    )
+    _assert_alias_read_constants_live(_check(CONSTANTS_BODY, str(constants_path)))
+
+
+def test_does_not_flag_constant_read_via_plain_module_name_attribute(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from report_constants import render_report_constants\n"
+        "\n"
+        "def label(medium: str) -> str:\n"
+        "    if medium == render_report_constants.MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    if medium == render_report_constants.MEDIUM_CODE:\n"
+        "        return 'code'\n"
+        "    return 'other'\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", CONSTANTS_BODY, consumer_body
+    )
+    _assert_alias_read_constants_live(_check(CONSTANTS_BODY, str(constants_path)))

package/hooks/blocking/test_verification_verdict_store.py

@@ -211,6 +211,18 @@ def test_corrective_message_scopes_comment_exemption_to_python() -> None:
     assert "comment-, and test-only surfaces are exempt" not in lowered_message
 
 
+def test_corrective_message_names_worktree_surface_keying() -> None:
+    lowered_message = CORRECTIVE_MESSAGE.lower()
+    assert "work tree" in lowered_message
+    assert "byte-identical" in lowered_message
+
+
+def test_corrective_message_gives_cross_worktree_remedy() -> None:
+    lowered_message = CORRECTIVE_MESSAGE.lower()
+    assert "run this command from the work tree" in lowered_message
+    assert "verify this surface here" in lowered_message
+
+
 def test_untracked_claude_production_hook_is_gated(tmp_path: pathlib.Path) -> None:
     work_dir = _make_repo_with_origin(tmp_path)
     new_hook_dir = work_dir / ".claude" / "hooks" / "blocking"