claude-dev-env 7.7.1 → 8.0.0

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:

package/hooks/validators/test_code_quality_checks.py

@@ -127,3 +127,25 @@ class TestFileLength:
             assert "400" in violations[0].message or "lines" in violations[0].message.lower()
         finally:
             temp_path.unlink()
+
+
+class TestTestFileExemption:
+    def test_long_function_in_a_test_file_passes(self) -> None:
+        tree = ast.parse(BAD_LONG_FUNCTION)
+        violations = check_function_length(tree, "packages/app/test_widget.py")
+        assert violations == []
+
+    def test_long_function_outside_a_test_file_still_fails(self) -> None:
+        tree = ast.parse(BAD_LONG_FUNCTION)
+        violations = check_function_length(tree, "packages/app/widget.py")
+        assert len(violations) == 1
+
+    def test_long_test_file_passes(self, tmp_path: Path) -> None:
+        temp_path = tmp_path / "test_widget.py"
+        temp_path.write_text("x = 1\n" * 450, encoding="utf-8")
+        assert check_file_length(temp_path) == []
+
+    def test_long_conftest_passes(self, tmp_path: Path) -> None:
+        temp_path = tmp_path / "conftest.py"
+        temp_path.write_text("x = 1\n" * 450, encoding="utf-8")
+        assert check_file_length(temp_path) == []

package/package.json

@@ -1,11 +1,10 @@
 {
     "name": "claude-dev-env",
-    "version": "7.7.1",
+    "version": "8.0.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs",
-        "cde-pstack": "bin/pstack.mjs",
         "codex-compat": "bin/codex-compat.mjs",
         "cde": "bin/cde.mjs"
     },

package/rules/ci-owns-the-gate.md

@@ -0,0 +1,58 @@
+# CI Owns the Gate
+
+**When this applies:** Before pushing a branch, and any time a repository's full
+check suite or policy gate is about to run on your own machine.
+
+## Rule
+
+The gate runs once, and it runs on CI. Push the branch, read the verdict, act on
+what it says.
+
+The inner development loop stays yours. Run the single test you are writing, as
+often as it helps. That is how the change gets built. This rule governs the
+second full pass, the one whose only product is a prediction of CI's answer.
+Push instead, and spend the wait on the next piece of work.
+
+## Why
+
+**A pinned gate answers only from its pinned revision.** The workflow names an
+exact revision of the policy package, and that revision decides which rules run.
+The copy under your home directory is a separate artifact at its own revision. A
+run against the home copy reports on those rules, which are a different question
+from the one CI asks. Treat its exit code as information about the home copy
+alone.
+
+**Self-hosted runners often share your machine.** Where the runners execute on
+the same host as your shell, a local suite run draws its processor time from the
+runners, and it does so while they work on the branch you just pushed. Read
+where the runners live, and count a local run against the same budget.
+
+**One authoritative answer beats two.** Where both runs agree, the second one
+restated the first. Where they differ, the environments differ, and CI is the
+environment that decides.
+
+## Running a gate locally
+
+Clone the revision the workflow pins, then point the gate at that clone. That
+run asks CI's question and its answer carries. Report a local result by naming
+the revision it used, so a reader can tell which question it answered.
+
+## The verdict belongs to CI
+
+CI decides whether a change passed, from evidence CI gathered. Keep that loop
+closed. A flag, trailer, receipt, or environment variable through which the
+change under test announces its own result hands the verdict to the subject.
+Where the runner and the agent share one host, a signature names the same party
+twice, so it carries the claim no further.
+
+A cache stays available on one condition. CI derives the key itself from the
+tree it is about to test, looks for a previous run under that key, and
+republishes that result. CI computes, CI verifies, CI decides.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`git-workflow.md`](git-workflow.md) | Confirm each required context fired after the push |
+| [`verify-runtime-state.md`](verify-runtime-state.md) | A status field is a report; read the thing the work was meant to make |
+| [`falsify-before-green.md`](falsify-before-green.md) | A green counts as evidence once the check has run red on a deliberate break |

package/rules/code-standards.md

@@ -2,7 +2,7 @@
 
 > **Canonical review contract:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — the human and AI review contract for code quality, loaded on demand.
 > **Checked-in pointer:** [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md) — the file Cursor BugBot reads; it points at `CODE_RULES.md`.
-> **Production enforcement.** The staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file. No write-time hook runs it. Use `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit, and CI runs the same lint against the merge base. Each mechanical rule carries a synchronization test.
+> **Production enforcement.** The staged policy lint runs `hooks/blocking/code_rules_enforcer.py` over each changed file. No write-time hook runs it. CI runs that lint against the merge base. Each mechanical rule carries a synchronization test.
 
 ## Policy surface map
 
@@ -27,7 +27,6 @@ BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers
 
 | Concern | Rule file |
 |---|---|
-| Question routing | [`ask-user-question-required.md`](ask-user-question-required.md) |
 | Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
 | Multi-step task list | skill `task-build` (see agents catalog) |
 

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

@@ -28,13 +28,13 @@ Read the body and the docstring side by side. Apply each check that matches the
 - **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
 - **Returns / Raises / Note claims** — each free-form claim matches the body.
 
-Many deterministic shapes of this drift are checked in `code_rules_docstrings.py` (and the JS and `.mjs` slices in `code_rules_imports_logging.py`). The staged policy lint reaches both through `code_rules_enforcer.py`, and no write-time hook runs them. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. Free-form rest is judgment.
+Many deterministic shapes of this drift are checked in `code_rules_docstrings.py` (and the JS and `.mjs` slices in `code_rules_imports_logging.py`). The staged policy lint reaches both through `code_rules_enforcer.py`, and CI runs it against the merge base. Free-form rest is judgment.
 
 ## Hook prose matches its detector
 
 A hook module is the sharpest case of the same rule: its docstring lead narrative and its `CORRECTIVE_MESSAGE` describe exactly the shapes the detector flags, and claim no broader trigger surface than the regex enforces.
 
-The staged policy lint carries this as its `hook-prose-consistency` rule, covering hook modules and their `*_constants.py` companions. It reports prose that claims a trigger the detector never fires on, and names the fix. No write-time hook runs it, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit.
+The staged policy lint carries this as its `hook-prose-consistency` rule, covering hook modules and their `*_constants.py` companions. It reports prose that claims a trigger the detector never fires on, and names the fix. No write-time hook runs it, so CI is where it reports.
 
 After writing a hook, ask: would a token matching every word of this message actually trip the detector? When the message names a shape the regex skips, rewrite the message to name only what the regex catches. The path-shape case is the common overstatement — a detector that keys off a path separator must not claim it blocks an "output-key segment". The corrective message spells the rewrite.
 

package/rules/failure-blast-radius.md

@@ -64,7 +64,7 @@ The report then presents each candidate to the owner for a durable-fix decision,
 
 ## Enforcement
 
-`code_rules_blast_radius.py` runs inside `code_rules_enforcer.py`, which the staged policy lint applies to each changed file under its `code-rules` rule. No write-time hook runs it, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+`code_rules_blast_radius.py` runs inside `code_rules_enforcer.py`, which the staged policy lint applies to each changed file under its `code-rules` rule. No write-time hook runs it, so CI is where it reports. CI runs the same lint against the merge base.
 
 The check requires each raised type written directly inside a loop body to end in `RunFatal` or `ItemBlocked`. The lexical check covers raises written directly in loop bodies. Shared helpers carry multiple caller contexts, so their callers classify the boundary.
 

package/rules/git-workflow.md

@@ -29,9 +29,10 @@ opens with the bot's own marker line. The description rules in this file, the
 failure signature in the release job log reads
 `could not parse pull request body as a release PR`.
 
-Use the `pr-description-writer` agent before creating a pull request or
-rewriting its full description. Publish its title and body file through
-`.agents/skills/pull-request/scripts/pull_request.py`.
+The `pr-description-writer` agent writes a title and body from the diff when
+you want one. Publish the title and body file through
+`~/.agents/skills/pull-request/scripts/pull_request.py`. That path is under the
+agents home, not the repository. A worktree holds no `.agents/` copy.
 
 Resolve the active managed root (`CLAUDE_CONFIG_DIR` when set, `~/.claude`
 otherwise), then run `<managed-root>/scripts/durable_post_lint.py` before any
@@ -50,14 +51,25 @@ untouched.
    - Before push: `gh pr ready --undo`
    - After review approved: `gh pr ready`
 
-## Run the required checks locally before the first push
+## Confirm the required checks fired, and let CI run them
 
-Read the branch ruleset for the required check contexts before you push a branch,
-or any level of a stack: `gh api repos/<owner>/<repo>/rules/branches/<trunk>`.
-Then run that exact gate command locally against that level's own base, on every
-level. A required check that never fired is invisible debt at every level, and it
-surfaces only after the whole stack is pushed, when the repair costs a second pass
-over every branch.
+The gate runs once, and it runs on CI. Push the branch and read its verdict.
+[`ci-owns-the-gate.md`](ci-owns-the-gate.md) holds the reasoning and the shape
+a local run takes when one is warranted.
+
+Read the branch ruleset for the required check contexts before you push a
+branch, or any level of a stack: `gh api repos/<owner>/<repo>/rules/branches/<trunk>`.
+Read it to learn which checks must report. After the push, confirm each of those
+contexts appears on that level's head. A required check that never fired is
+invisible debt at every level, and it surfaces only after the whole stack is
+pushed, when the repair costs a second pass over every branch.
+
+A red required check blocks the branch, whoever owns the failing line. The gate
+charges a change for the whole file it touches, so "pre-existing on main" is a
+blame note, not a pass. Fix the line in the next push or report the branch
+blocked. Read the gate's own report rather than a narrower substitute. A
+single-file mypy call cannot see sibling modules and reports false import
+errors, so it neither clears nor convicts a change.
 
 A checks listing that reports nothing on the branch is a finding, not a neutral
 state. Find out whether the workflow's event filters exclude the branch, or whether
@@ -82,7 +94,7 @@ what it calls.
 Force-with-lease protects the ref. It protects nobody's understanding of what the
 branch now holds. When a rewrite moves content between levels of a stack, or
 otherwise changes what a branch contains, refresh that pull request's description
-through the `pr-description-writer` agent before you ask anyone to read or merge it.
+before you ask anyone to read or merge it.
 
 ## Never commit working documents or images
 

package/rules/orphan-css-class.md

@@ -15,7 +15,7 @@ When you add a `class="..."` attribute, add its `.<class>` selector to the `<sty
 
 ## What the check covers
 
-The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` reaches production Python through the staged policy lint, whose `code-rules` rule loads `code_rules_enforcer.py` and applies it to each changed file. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. It:
+The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` reaches production Python through the staged policy lint, whose `code-rules` rule loads `code_rules_enforcer.py` and applies it to each changed file. CI runs that lint against the merge base. It:
 
 1. Collects each class name referenced in a `class="..."` attribute across the file's string literals.
 2. Collects each class selector defined in a `<style>` block — both in the file under edit and in every Python module beside it (its own directory and immediate child directories), since a markup module commonly imports its style constant from a companion package directory.

package/rules/paired-test-coverage.md

@@ -18,7 +18,7 @@ When you add a public function to a module whose test suite already exercises th
 
 ## What the check covers
 
-Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. The two checks cover the two write orders.
+Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so CI is where they report, against the merge base. The two checks cover the two write orders.
 
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 

package/rules/retired-hook-prose.md

@@ -7,7 +7,7 @@ paths:
 
 A hook module runs when `hooks/hooks.json` registers it or a dispatcher roster hosts it. A module can survive on disk while appearing in neither place, and it then reaches no tool call. Prose that gives such a module a present-tense action describes a gate the reader never faces, and a reader who trusts it skips the check they were meant to run by hand.
 
-The staged policy lint carries this check as its `retired-hook-prose` rule. It reads each Markdown file under a `rules/` directory, takes every backticked hook module name, and reports the ones that are registered nowhere and that carry a present-tense action verb in the rest of the sentence. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+The staged policy lint carries this check as its `retired-hook-prose` rule. It reads each Markdown file under a `rules/` directory, takes every backticked hook module name, and reports the ones that are registered nowhere and that carry a present-tense action verb in the rest of the sentence. CI runs that lint against the merge base.
 
 A module name counts as a hook when it ends in one of the hook families, such as `_blocker`, `_enforcer`, `_gate`, `_tracker`, or `_dispatcher`, and when it either sits under `hooks/` or appears in `RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS` in `bin/install.mjs`. A support module inside the hooks tree carries no such family suffix, so it stays out of the check. A hook deleted from disk without an entry in that roster resolves nowhere, so add the roster entry when you retire a hook.
 

package/rules/verify-before-asking.md

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

package/rules/windows-filesystem-safe.md

@@ -12,6 +12,6 @@ Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` file
 
 In Node, call `mkdirSync(targetPath, { recursive: true })` on possibly-existing paths — `ReadOnly` directories break the non-recursive form. When the call must be non-recursive, strip the attribute first (`(Get-Item $path -Force).Attributes = "Directory"` / `os.chmod(path, stat.S_IWRITE)`).
 
-The staged policy lint carries this check as its `rmtree-safety` rule. It reports the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+The staged policy lint carries this check as its `rmtree-safety` rule. It reports the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code. CI runs that lint against the merge base.
 
 Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first, so a fix lands in one and the other keeps the bug (CODE_RULES.md, CORE PRINCIPLES, "Reuse before create"). The same `rmtree-safety` lint rule reports a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` check, which a copy between two distant packages slips past.

package/rules/workflow-substitution-slots.md

@@ -9,4 +9,4 @@ In a `.workflow.js` agent-prompt template, every per-call or per-iteration value
 
 When a loop builds a per-iteration path or output key, write the index as a slot — `cand_<i>` — or spell out `replace <i> with the iteration index 0, 1, 2` in the step text. Every per-call value in a `.workflow.js` template carries angle brackets so an agent fills in a fresh value per call.
 
-The staged policy lint carries this check as its `workflow-substitution` rule. It reports a `.workflow.js` file whose looped content holds a bare `<word>_<i|j|k>` token as a per-iteration path segment. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. No write-time hook reports this, so a bare token stays on disk until the lint runs.
+The staged policy lint carries this check as its `workflow-substitution` rule. It reports a `.workflow.js` file whose looped content holds a bare `<word>_<i|j|k>` token as a per-iteration path segment. CI runs that lint against the merge base. No write-time hook reports this, so a bare token stays on disk until the lint runs.