claude-dev-env 7.7.1 → 8.1.0

package/bin/resolve-install-root.mjs

@@ -60,6 +60,7 @@ export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
  *   hooksLookupDirectory: string,
  *   scriptsLookupDirectory: string,
  *   codexHooksInstallDirectory: string,
+ *   codexHomeDirectory: string,
  * }} InstallRootResolution
  */
 
@@ -179,6 +180,7 @@ export function resolveInstallRoot(options = {}) {
         hooksLookupDirectory,
         scriptsLookupDirectory,
         codexHooksInstallDirectory,
+        codexHomeDirectory,
     };
 }
 

package/bin/resolve-install-root.test.mjs

@@ -0,0 +1,69 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+    resolveInstallRoot,
+    CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE,
+    DEFAULT_CLAUDE_DIRECTORY_NAME,
+} from './resolve-install-root.mjs';
+import {
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    CODEX_HOOKS_DIRECTORY_NAME,
+    CODEX_RULES_DIRECTORY_NAME,
+    DEFAULT_CODEX_DIRECTORY_NAME,
+    MANAGED_SKILLS_DIRECTORY_NAME,
+    PACKAGE_AGENTS_HOME_DIRECTORY_NAME,
+} from './install-constants.mjs';
+
+const HOME_DIRECTORY = join(tmpdir(), 'cdev-resolve-roots-home');
+
+function resolveFrom(environment, explicitTarget = null) {
+    return resolveInstallRoot({ homeDirectory: HOME_DIRECTORY, environment, explicitTarget });
+}
+
+test('the managed root falls back to the default Claude directory under the home', () => {
+    const resolution = resolveFrom({});
+    assert.equal(resolution.managedRoot, join(HOME_DIRECTORY, DEFAULT_CLAUDE_DIRECTORY_NAME));
+    assert.equal(resolution.source, 'default-home');
+});
+
+test('CLAUDE_CONFIG_DIR names the managed root and an explicit target outranks it', () => {
+    const configuredRoot = join(tmpdir(), 'cdev-configured');
+    const explicitRoot = join(tmpdir(), 'cdev-explicit');
+    const configured = resolveFrom({ [CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE]: configuredRoot });
+    assert.equal(configured.managedRoot, configuredRoot);
+    assert.equal(configured.source, 'claude-config-dir');
+
+    const explicit = resolveFrom(
+        { [CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE]: configuredRoot },
+        explicitRoot,
+    );
+    assert.equal(explicit.managedRoot, explicitRoot);
+    assert.equal(explicit.source, 'explicit-target');
+});
+
+test('the Codex home is the directory holding the rules and hooks destinations', () => {
+    const resolution = resolveFrom({});
+    const codexHome = join(HOME_DIRECTORY, DEFAULT_CODEX_DIRECTORY_NAME);
+    assert.equal(resolution.codexHomeDirectory, codexHome);
+    assert.equal(resolution.codexRulesInstallDirectory, join(codexHome, CODEX_RULES_DIRECTORY_NAME));
+    assert.equal(resolution.codexHooksInstallDirectory, join(codexHome, CODEX_HOOKS_DIRECTORY_NAME));
+});
+
+test('CODEX_HOME relocates the Codex home the pstack plugin step installs into', () => {
+    const relocatedHome = join(tmpdir(), 'cdev-relocated-codex');
+    const resolution = resolveFrom({ [CODEX_HOME_ENVIRONMENT_VARIABLE]: relocatedHome });
+    assert.equal(resolution.codexHomeDirectory, relocatedHome);
+    assert.equal(resolution.codexRulesInstallDirectory, join(relocatedHome, CODEX_RULES_DIRECTORY_NAME));
+});
+
+test('a managed root named .claude pairs with the sibling agents home', () => {
+    const resolution = resolveFrom({});
+    assert.equal(resolution.agentsHome, join(HOME_DIRECTORY, PACKAGE_AGENTS_HOME_DIRECTORY_NAME));
+    assert.equal(resolution.skillsInstallDirectory, join(HOME_DIRECTORY, PACKAGE_AGENTS_HOME_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME));
+    assert.equal(
+        resolution.skillsLookupDirectory,
+        join(HOME_DIRECTORY, DEFAULT_CLAUDE_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME),
+    );
+});

package/docs/CODE_RULES.md

@@ -31,7 +31,7 @@ Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX,
 
 no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`; `/migrations/`; Workflow registries: path contains any of these substrings — `/workflow/`, `_tab.py`, `/states.py`, or `/modules.py`, each matching independently as a substring, so `pkg/states.py` qualifies while a top-level `states.py` follows the standard `config/` rule; test files — path or filename matches `test_`, `_test.`, `.spec.`, `conftest`, or `/tests/`) · no hardcoded user home paths · guarded `sys.path.insert` · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost) · JavaScript/TypeScript boolean declarations (`const`/`let`/`var` bound to a boolean literal or negation) and `@param {boolean}` JSDoc names prefixed `is`/`has`/`should`/`can`/`was`/`did` (camelCase forms) · banned identifiers as `.mjs`/`.js` declaration names (`result`, `data`, `ctx`, `msg`, …), scoped to changed lines · in test files, banned identifiers fire on changed lines, and pytest-collectable `test_*` functions need a return annotation · unused module-level imports and unsorted import blocks are ruff's job (F401, isort I001), not this hook's · a `hooks/blocking/` command classifier anchors its multi-word command regex to the command start (`^`/`\A`) or tokenizes the first word (`shlex.split`), never matching a command as a bare substring
 
-Test files follow the comment policy above; other test-specific exemptions are listed here. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
+Test files follow the comment policy above; other test-specific exemptions are listed here. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks.
 
 ---
 

package/docs/agent-spawn-protocol.md

@@ -1,6 +1,6 @@
 # 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.
+Full protocol for briefing a subagent. It applies before any Agent or Task tool invocation — Explore, implementation, research, or team subagents.
 
 ## Step 1: Context sufficiency check
 

package/docs/codex-compatibility.md

@@ -65,22 +65,10 @@ hand when the host should receive that context.
 
 ## Luna fast-mode guard
 
-`hooks/blocking/luna_fast_mode_gate.py` serves Claude and Codex. Codex reads its own `hooks.json`, so add this `PreToolUse` group to that file. Replace `<CODEX_HOOKS_ROOT>` with the directory that holds the shipped hook:
-
-```json
-{
-  "matcher": "Agent|Task|multi_agent_v1__spawn_agent",
-  "hooks": [
-    {
-      "type": "command",
-      "command": "python <CODEX_HOOKS_ROOT>/blocking/luna_fast_mode_gate.py",
-      "timeout": 10
-    }
-  ]
-}
-```
-
-The guard requires exact `fast` for Luna spawns through `Agent` and `Task`. Native Codex `multi_agent_v1__spawn_agent` accepts exact `fast` or `priority`. Other models and tools pass through.
+Commit `0f21faf8` retired `luna_fast_mode_gate.py` with the other blocking
+policy hooks. The package ships no replacement, so a Codex `hooks.json` needs
+no entry for it, and the spawn tier a Luna spawn asks for is the caller's to
+hold.
 
 ## Roots and safety
 

package/docs/nas-ssh-invocation.md

@@ -23,7 +23,7 @@ from there when something needs them, and keep them out of anything committed or
 
 Write the script file with the Write tool. Keeping the commands in a file has a second benefit: a
 destructive word such as `rm -rf` inside the file never appears in a Bash tool command string, so the
-`destructive_command_blocker` hook stays out of the way.
+harness permission prompt never fires on it and an unattended run keeps going.
 
 The script runs through `bash -s` in a single shell. Variables, `cd`, and `source` all carry from one
 line to the next. Standard output, standard error and the exit code all come back.

package/docs/references/prose-style-enforcement.md

@@ -10,8 +10,8 @@ The flag is `PROSE_STYLE_ENFORCEMENT_ENABLED` in `hooks/blocking/config/prose_st
 
 ## Always on
 
-Structural AskUserQuestion lean-block validation in `ask_user_question_shape_blocker` (chat detail, length caps on question blocks) stays active regardless of the flag. Historical/comparative language detection in `state_description_blocker.py` runs unconditionally and does not read this flag. Apply `rules/asd-ste100-language.md` for user-facing word choice and sentence style. Code-rules and security blockers are out of scope for this switch.
+Historical/comparative language detection in `state_description_blocker.py` runs unconditionally and does not read this flag. Apply `rules/asd-ste100-language.md` for user-facing word choice and sentence style. Code-rules and security blockers are out of scope for this switch.
 
 ## Hedging claims
 
-Hedge-word discipline is prose guidance, not a hook: `rules/hedging-claims.md`. State a claim with its evidence, or label it unverified in the same sentence as the hedge word.
+Hedge-word discipline is prose guidance, not a hook. State a claim with its evidence, or label it unverified in the same sentence as the hedge word.

package/hooks/HOOK_SPECS_PROMPT_WORKFLOW.md

@@ -49,6 +49,4 @@ Generated prompt-workflow outputs must declare, in their audit frontmatter:
 - `base_minimal_instruction_layer: true`
 - `on_demand_skill_loading: true`
 
-The Stop guard blocks responses that omit either signal. These signals are
-the machine-checkable counterpart to the policy text in
-`rules/prompt-workflow-context-controls.md`.
+The Stop guard blocks responses that omit either signal.

package/hooks/blocking/code_rules_constants_config.py

@@ -1,4 +1,4 @@
-"""Constants-outside-config checks and the file-global constant use-count check.
+"""Constants-outside-config checks.
 
 Also carries check_config_duplicate_path_anchor, which flags a config module
 that rebuilds a directory a sibling module in the same package already
@@ -22,7 +22,6 @@ from code_rules_path_utils import (  # noqa: E402
     is_config_file,
 )
 from code_rules_shared import (  # noqa: E402
-    _build_parent_map,
     docstring_line_numbers,
     get_file_extension,
     is_migration_file,
@@ -35,7 +34,6 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_PYTHON_EXTENSIONS,
-    FILE_GLOBAL_UPPER_SNAKE_PATTERN,
 )
 
 
@@ -164,111 +162,6 @@ def check_constants_outside_config_advisory(content: str, file_path: str) -> Non
         sys.stderr.write(f"[CODE_RULES advisory] {file_path}: {each_issue}\n")
 
 
-def _is_upper_snake_constant_name(name: str) -> bool:
-    """Return True for UPPER_SNAKE identifiers including those with a leading underscore."""
-    return bool(FILE_GLOBAL_UPPER_SNAKE_PATTERN.match(name))
-
-
-def _collect_module_level_upper_snake_constants(
-    module_tree: ast.Module,
-) -> dict[str, int]:
-    """Return mapping of module-level UPPER_SNAKE constant name to its line number."""
-    constants_by_name: dict[str, int] = {}
-    for each_node in module_tree.body:
-        if isinstance(each_node, ast.Assign):
-            for each_target in each_node.targets:
-                if isinstance(each_target, ast.Name) and _is_upper_snake_constant_name(each_target.id):
-                    constants_by_name.setdefault(each_target.id, each_node.lineno)
-        elif isinstance(each_node, ast.AnnAssign):
-            if isinstance(each_node.target, ast.Name) and _is_upper_snake_constant_name(each_node.target.id):
-                constants_by_name.setdefault(each_node.target.id, each_node.lineno)
-    return constants_by_name
-
-
-def _resolve_enclosing_function_qname(
-    load_node: ast.Name,
-    parent_by_child_id: dict[int, ast.AST],
-) -> Optional[str]:
-    """Return 'ClassName.function_name' or 'function_name' for the enclosing function.
-
-    Returns None when the reference is at module scope (no enclosing function).
-    Decorator expressions on a function/method count as belonging to that function.
-    """
-    enclosing_function_name: Optional[str] = None
-    enclosing_class_name: Optional[str] = None
-    current_ancestor = parent_by_child_id.get(id(load_node))
-    while current_ancestor is not None:
-        if isinstance(current_ancestor, (ast.FunctionDef, ast.AsyncFunctionDef)) and enclosing_function_name is None:
-            enclosing_function_name = current_ancestor.name
-        elif isinstance(current_ancestor, ast.ClassDef):
-            enclosing_class_name = current_ancestor.name
-            break
-        current_ancestor = parent_by_child_id.get(id(current_ancestor))
-    if enclosing_function_name is None:
-        if enclosing_class_name is not None:
-            return f"<class:{enclosing_class_name}>"
-        return None
-    if enclosing_class_name is not None:
-        return f"{enclosing_class_name}.{enclosing_function_name}"
-    return enclosing_function_name
-
-
-def check_file_global_constants_use_count(content: str, file_path: str) -> list[str]:
-    """Flag module-level UPPER_SNAKE constants referenced by only one function/method.
-
-    Enforces the file-global-constants use-count rule: a constant used by just
-    one caller belongs in that caller's scope. Test files, config files,
-    workflow-registry files, and non-Python files are exempt. Constants with
-    zero references are out of scope. The enforcer entry module
-    (``hooks/blocking/code_rules_enforcer.py``) is exempt to avoid
-    self-blocking.
-    """
-    if is_test_file(file_path):
-        return []
-    if is_config_file(file_path):
-        return []
-    if is_workflow_registry_file(file_path):
-        return []
-    if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
-        return []
-    if file_path.replace("\\", "/").endswith("hooks/blocking/code_rules_enforcer.py"):
-        return []
-
-    try:
-        module_tree = ast.parse(content)
-    except SyntaxError:
-        return []
-
-    constants_by_name = _collect_module_level_upper_snake_constants(module_tree)
-    if not constants_by_name:
-        return []
-
-    parent_by_child_id = _build_parent_map(module_tree)
-    callers_by_constant: dict[str, set[str]] = {name: set() for name in constants_by_name}
-    for each_node in ast.walk(module_tree):
-        if not isinstance(each_node, ast.Name):
-            continue
-        if not isinstance(each_node.ctx, ast.Load):
-            continue
-        if each_node.id not in callers_by_constant:
-            continue
-        enclosing_qname = _resolve_enclosing_function_qname(each_node, parent_by_child_id)
-        if enclosing_qname is None:
-            callers_by_constant[each_node.id].add("<module-scope>")
-        else:
-            callers_by_constant[each_node.id].add(enclosing_qname)
-
-    issues: list[str] = []
-    for each_constant_name, each_line_number in sorted(constants_by_name.items(), key=lambda pair: pair[1]):
-        caller_count = len(callers_by_constant[each_constant_name])
-        if caller_count == 1:
-            issues.append(
-                f"Line {each_line_number}: File-global constant {each_constant_name} used by only 1 function/method - move to method scope or add a second caller"
-            )
-
-    return issues
-
-
 def _references_dunder_file(node: ast.AST) -> bool:
     """Return True when the expression tree reads ``__file__``."""
     return any(

package/hooks/blocking/code_rules_enforcer.py

@@ -60,7 +60,6 @@ from code_rules_constants_config import (  # noqa: E402
     check_config_duplicate_path_anchor,
     check_constants_outside_config,
     check_constants_outside_config_advisory,
-    check_file_global_constants_use_count,
 )
 from code_rules_docstrings import (  # noqa: E402
     check_class_docstring_names_public_methods,
@@ -358,7 +357,6 @@ def _python_magic_value_and_constant_issues(context: _ValidationContext) -> list
     all_issues.extend(check_fstring_structural_literals(content, file_path))
     all_issues.extend(check_constants_outside_config(content, file_path))
     check_constants_outside_config_advisory(content, file_path)
-    all_issues.extend(check_file_global_constants_use_count(content, file_path))
     return all_issues
 
 
@@ -1240,7 +1238,9 @@ def _deny_reason_for_issues(
     Returns:
         The complete ``permissionDecisionReason`` text.
     """
-    issue_list = "; ".join(all_blocking_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT])
+    issue_list = VIOLATION_SEPARATOR.join(
+        all_blocking_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT]
+    )
     deny_reason = (
         f"BLOCKED: [CODE_RULES] {len(all_blocking_issues)} violation(s): {issue_list}"
     )
@@ -1257,7 +1257,9 @@ def _deny_reason_for_issues(
             all_blocking_issues=all_blocking_issues,
         )
         if forecast_issues:
-            forecast_list = "; ".join(forecast_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT])
+            forecast_list = VIOLATION_SEPARATOR.join(
+                forecast_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT]
+            )
             deny_reason += (
                 f"; FULL-FILE FORECAST — {len(forecast_issues)} additional "
                 "violation(s) elsewhere in this file will block future edits "
@@ -1362,7 +1364,9 @@ def _report_hook_blocking_issues(
     )
     if not all_blocking_issues:
         return
-    issue_list = "; ".join(all_blocking_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT])
+    issue_list = VIOLATION_SEPARATOR.join(
+        all_blocking_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT]
+    )
     deny_reason = (
         f"BLOCKED: [CODE_RULES] {len(all_blocking_issues)} violation(s): {issue_list}"
         + _precheck_hint()

package/hooks/blocking/code_rules_test_layout.py

@@ -10,8 +10,8 @@ test functions, which exports nothing, so a single-file scan proves a constant
 no other line reads is dead. A ``conftest.py``, a shared helper module reached
 only through the ``tests/`` directory gate, and a dedicated constants or
 ``config/`` module all export their constants to importer modules, so the
-audit lane governs their constants cross-module (see
-rules/file-global-constants.md) and this write-time check leaves them alone.
+audit lane governs their constants cross-module and this write-time check
+leaves them alone.
 """
 
 import ast
@@ -54,7 +54,7 @@ def _is_dead_constant_scan_target(file_path: str) -> bool:
     constant no other line reads is dead. A ``conftest.py``, a shared helper
     module reached only through the ``tests/`` directory gate, and a dedicated
     constants or ``config/`` module all export to importer modules, where the
-    cross-module audit lane governs their constants (see rules/file-global-constants.md).
+    cross-module audit lane governs their constants.
 
     Args:
         file_path: The destination path of the write.
@@ -77,8 +77,8 @@ def _is_private_constant_name(name: str) -> bool:
         EXPECTED_TOTAL           ->  public constant, left alone
 
     Only a leading-underscore name qualifies. A public module constant exports
-    to importer modules, so the cross-module audit lane governs it (see
-    rules/file-global-constants.md) and this single-file scan leaves it alone.
+    to importer modules, so the cross-module audit lane governs it and this
+    single-file scan leaves it alone.
     """
     if not name.startswith(PRIVATE_NAME_PREFIX):
         return False
@@ -163,8 +163,7 @@ def check_dead_test_module_constant(content: str, file_path: str) -> list[str]:
     dead scaffolding an edit stranded. A public constant, a ``conftest.py``, a
     shared helper module under ``tests/``, and a dedicated constants or
     ``config/`` module all export to importer modules, so the cross-module
-    audit lane judges those (see rules/file-global-constants.md) and this
-    check skips them.
+    audit lane judges those and this check skips them.
 
     Args:
         content: The post-edit file content under validation.

package/hooks/blocking/test_code_rules_constants_config.py

@@ -24,3 +24,16 @@ def test_module_source_carries_no_docstring_magic_value() -> None:
         "bare-number token that the magic-value check flags as a literal, "
         f"got: {magic_value_issues}"
     )
+
+
+ARCHIVED_USE_COUNT_CHECK_NAME = "check_file_global_constants_use_count"
+
+
+def test_module_defines_no_check_for_an_archived_rule() -> None:
+    module_path = Path(__file__).resolve().parent / "code_rules_constants_config.py"
+    module_source = module_path.read_text(encoding="utf-8")
+    assert ARCHIVED_USE_COUNT_CHECK_NAME not in module_source, (
+        "The file-global constant use-count rule moved to rules-archived, so this "
+        "module must define no check that enforces it. Code left behind keeps "
+        "enforcing a rule the package no longer documents."
+    )

package/hooks/blocking/test_code_rules_enforcer_cap_meta.py

@@ -71,7 +71,6 @@ KNOWN_UNCAPPED_CHECKS_PENDING_REVIEW: frozenset[str] = frozenset(
         "check_constant_equality_tests",
         "check_constants_outside_config",
         "check_existence_check_tests",
-        "check_file_global_constants_use_count",
         "check_imports_at_top",
         "check_inline_literal_collections",
         "check_join_separator_string_magic",

package/hooks/blocking/test_code_rules_enforcer_dispatch_wiring.py

@@ -173,3 +173,18 @@ def test_known_undispatched_set_lists_only_existing_checks() -> None:
         f"KNOWN_UNDISPATCHED_CHECKS lists functions that no longer exist: "
         f"{sorted(stale_names)}. Restore the function or remove it from the set."
     )
+
+
+ARCHIVED_USE_COUNT_CHECK_NAME = "check_file_global_constants_use_count"
+
+
+def test_enforcer_dispatches_no_check_for_an_archived_rule() -> None:
+    enforcer_source = (_HOOK_DIRECTORY / "code_rules_enforcer.py").read_text(
+        encoding="utf-8"
+    )
+    assert ARCHIVED_USE_COUNT_CHECK_NAME not in enforcer_source, (
+        "The file-global constant use-count rule moved to rules-archived, so the "
+        "enforcer must import and dispatch no check that enforces it. A check "
+        "left wired here blocks a write against a rule the package no longer "
+        "documents."
+    )

package/hooks/blocking/test_code_rules_enforcer_split_constants_config.py

@@ -20,7 +20,6 @@ from code_rules_constants_config import (  # noqa: E402
     _scan_function_body_constants,
     check_constants_outside_config,
     check_constants_outside_config_advisory,
-    check_file_global_constants_use_count,
 )
 
 code_rules_enforcer = SimpleNamespace(
@@ -28,7 +27,6 @@ code_rules_enforcer = SimpleNamespace(
     _scan_function_body_constants=_scan_function_body_constants,
     check_constants_outside_config=check_constants_outside_config,
     check_constants_outside_config_advisory=check_constants_outside_config_advisory,
-    check_file_global_constants_use_count=check_file_global_constants_use_count,
 )
 
 
@@ -37,37 +35,6 @@ CONSTANTS_OUTSIDE_CONFIG_PRODUCTION_FILE_PATH = "packages/app/services/encoding.
 PRODUCTION_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example_production.py"
 
 
-def test_should_flag_constant_used_only_in_class_level_decorator() -> None:
-    source = (
-        "TIMEOUT = 5\n"
-        "\n"
-        "def register(value):\n"
-        "    def wrap(cls):\n"
-        "        return cls\n"
-        "    return wrap\n"
-        "\n"
-        "@register(TIMEOUT)\n"
-        "class Foo:\n"
-        "    pass\n"
-    )
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert any(
-        "TIMEOUT" in issue and "only 1 function/method" in issue for issue in issues
-    ), f"Expected class-decorator usage to register as a caller, got: {issues}"
-
-
-def test_should_flag_constant_used_once_at_module_scope_and_once_in_function() -> None:
-    source = "UPPER = 1\nSHADOW = UPPER\n\ndef lonely_caller():\n    return UPPER\n"
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        source, PRODUCTION_FILE_PATH
-    )
-    assert issues == [], (
-        f"Expected module-scope + function usage to count as 2 distinct callers, got: {issues}"
-    )
-
-
 def test_is_exempt_for_advisory_scan_returns_true_for_config_file() -> None:
     assert code_rules_enforcer._is_exempt_for_advisory_scan("project/config/constants.py") is True
 
@@ -241,30 +208,3 @@ def test_check_constants_outside_config_reports_more_than_three_constants() -> N
     )
 
 
-_SINGLE_CALLER_CONSTANT_SOURCE = (
-    "TIMEOUT = 5\n"
-    "\n"
-    "def lonely_caller() -> int:\n"
-    "    return TIMEOUT\n"
-)
-
-_ENFORCER_ENTRY_FILE_PATH = "packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py"
-
-
-def test_use_count_flags_single_caller_constant_for_ordinary_production_path() -> None:
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        _SINGLE_CALLER_CONSTANT_SOURCE, PRODUCTION_FILE_PATH
-    )
-    assert any(
-        "TIMEOUT" in issue and "only 1 function/method" in issue for issue in issues
-    ), f"Expected single-caller constant flagged on an ordinary production path, got: {issues}"
-
-
-def test_use_count_exempts_enforcer_entry_module_path() -> None:
-    issues = code_rules_enforcer.check_file_global_constants_use_count(
-        _SINGLE_CALLER_CONSTANT_SOURCE, _ENFORCER_ENTRY_FILE_PATH
-    )
-    assert issues == [], (
-        "The enforcer entry module must be exempt to avoid self-blocking, "
-        f"got: {issues}"
-    )

package/hooks/blocking/test_context_control_policy_files.py

@@ -4,20 +4,9 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[2]
-RULE_PATH = ROOT / "rules" / "prompt-workflow-context-controls.md"
 HOOK_SPEC_PATH = ROOT / "hooks" / "HOOK_SPECS_PROMPT_WORKFLOW.md"
 
 
-def test_context_control_rule_exists_with_required_sections() -> None:
-    text = RULE_PATH.read_text(encoding="utf-8")
-    assert "Base Minimal Instruction Layer" in text
-    assert "On-Demand Skill Loading" in text
-    assert "Compaction and Caching Strategy" in text
-    assert "Runtime Enforcement Signals" in text
-    assert "base_minimal_instruction_layer: true" in text
-    assert "on_demand_skill_loading: true" in text
-
-
 def test_hook_spec_exists_with_required_gates() -> None:
     text = HOOK_SPEC_PATH.read_text(encoding="utf-8")
     assert "PreToolUse Task/Agent (removed)" in text

package/hooks/hooks_constants/blocking_check_limits.py

@@ -2,7 +2,7 @@
 
 Each constant is consumed by exactly one check function in the enforcer. They
 live here (not at module scope of the enforcer) so the enforcer file stays
-under the file-global-constants use-count rule (CODE_RULES §file-global-constants).
+because each has more than one consumer in this package.
 """
 
 from __future__ import annotations

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -185,7 +185,6 @@ DEAD_SPLIT_BRANCH_MESSAGE_SUFFIX: str = (
 )
 DUPLICATED_FORMAT_MINIMUM_REPETITION_COUNT = 3
 DUPLICATED_FORMAT_MINIMUM_LITERAL_CHARACTER_COUNT = 5
-FILE_GLOBAL_UPPER_SNAKE_PATTERN = re.compile(r"^_?[A-Z][A-Z0-9_]*$")
 
 ALL_COLLECTION_TYPE_NAMES: frozenset[str] = frozenset({
     "list", "tuple", "set", "frozenset",

package/hooks/hooks_constants/setup_project_paths_constants.py

@@ -1,8 +1,7 @@
 """Configuration constants for the setup_project_paths bootstrap script.
 
 Shared constants consumed by two or more modules across the hook subsystem.
-Single-use values are inlined into their consuming functions per the
-file-global-constants use-count rule.
+Single-use values are inlined into their consuming functions.
 """
 
 from __future__ import annotations

package/hooks/session/test_untracked_repo_detector.py

@@ -151,7 +151,7 @@ class TestSharedRegistryPath:
     def test_config_file_path_not_a_module_level_attribute(self) -> None:
         """Pin PR #230 round 7: _CONFIG_FILE_PATH inlined into _build_confirm_instruction.
 
-        Single-consumer module-level constant moved to local per file-global-constants rule.
+        Single-consumer module-level constant kept in the scope that reads it.
         """
         assert not hasattr(detector, "_CONFIG_FILE_PATH")
 

package/hooks/validators/code_quality_checks.py

@@ -1,9 +1,15 @@
 """Code quality checks validator.
 
 Implements:
-- Check 30: Function too long (max 30 lines)
+- Check 30: Function too long (max 30 lines), production files only
 - Check 31: Nesting too deep (max 2 levels)
-- Check 32: File too long (max 400 lines)
+- Check 32: File too long (max 400 lines), production files only
+
+The two length caps read production files only. A test module grows with the
+surface it covers, and a linear list of assertions is what a reader wants there,
+so capping its length pushes a contributor to split a suite for the counter
+rather than for the reader. ``magic_value_checks`` short-circuits on the same
+category through the same helper.
 """
 
 import ast
@@ -11,6 +17,7 @@ import sys
 from pathlib import Path
 from typing import List
 
+from .exempt_paths import is_test_file
 from .validator_base import Violation, source_text, syntax_tree
 
 
@@ -22,6 +29,9 @@ MAX_FILE_LINES = 400
 def check_function_length(tree: ast.AST, filename: str) -> List[Violation]:
     violations: List[Violation] = []
 
+    if is_test_file(filename):
+        return violations
+
     for node in ast.walk(tree):
         if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             if node.end_lineno and node.lineno:
@@ -74,6 +84,9 @@ def check_file_length(file_path: Path) -> List[Violation]:
     violations: List[Violation] = []
     filename = str(file_path)
 
+    if is_test_file(filename):
+        return violations
+
     try:
         lines = source_text(file_path).splitlines()
     except Exception as error: