claude-dev-env 1.35.0 → 1.36.1

package/agents/clean-coder.md

@@ -128,7 +128,7 @@ for each_user in all_users:
 
 ### Complete type hints
 
-Every parameter and return type is declared explicitly. `Any` is replaced with the concrete type. `# type: ignore` is replaced with a fix that resolves the underlying type issue.
+Every parameter and return type is declared explicitly. `Any` is replaced with the concrete type. When `# type: ignore` is genuinely necessary (a third-party type stub gap, an unavoidable runtime cast), append a trailing `# <reason>` of at least 5 characters explaining the constraint — the hook fires on bare `# type: ignore` without a justification. Output is mypy-clean: every file you write or edit passes `mypy_validator.py` at write time.
 
 ```python
 def fetch_orders_for_customer(customer_id: int) -> list[Order]:
@@ -149,6 +149,14 @@ def fetch_with_retries(url: str) -> str:
 
 String templates also count: when the structural literal text inside an f-string (paths, URLs, patterns) survives stripping the interpolations, that text is a magic value and belongs in config.
 
+Bare string literals also count when their shape is structural: a multi-segment path (`/api/v1/users`), a URL with scheme, a Windows drive prefix, a leading absolute path, a regex anchor (`^foo`, `bar$`), or a regex escape sequence (`\d`, `\w`, `\s`). Extract these to `config/constants.py`.
+
+Inline list and set literals of two or more constants in production function bodies move to `config/`. The hook fires on `[1, 2, 3]` or `{1, 2, 3}` inside a function body when every element is a constant — extract to a named module-level (or `config/`) constant.
+
+### Library print() and CLI markers
+
+Use logging for application and runtime output. `print()` is allowed when stdout is the integration contract: CLI entrypoints (paths under `/scripts/`, filenames ending `_cli.py`, `/cli.py`), or one-off automation helpers where the script's contract is its stdout (for example `print(json.dumps(...))`). The `check_library_print` hook fires on `print()` outside those path markers.
+
 ### Comment preservation
 
 Existing comments on lines that remain otherwise unchanged stay exactly as you found them. The hook enforces both directions: the gate fires on a new inline `#` or `//` in production code, and the gate also fires when an existing comment disappears from a line you touched. New code self-documents via names; new docstrings on functions, methods, classes, and modules remain allowed.
@@ -189,6 +197,8 @@ def fetch_with_retries(url: str) -> str:
 
 Production-code `UPPER_SNAKE = ...` at module scope outside `config/` is flagged. Exempt path families: `config/*`, `/migrations/`, `/workflow/`, `_tab.py`, `/states.py`, `/modules.py`, and all test files (`test_*.py`, `*_test.py`, `*.spec.*`, `conftest.py`, paths under `/tests/`).
 
+Function-local `UPPER_SNAKE_CASE = ...` (assigned inside a function body in production code) is a non-blocking advisory: it usually belongs in `config/`. Move the value when there is no caller-specific reason for the local form.
+
 ### Logging format
 
 Logging calls take the format string and arguments as separate parameters. The hook fires on any f-string passed to `log_*`.
@@ -247,10 +257,79 @@ def render_dashboard(profile: Profile) -> Dashboard:
 
 When `profile` is already loaded, build the dashboard from it; fetch only when the data is genuinely absent.
 
+### Test quality rules
+
+Tests document behavior. The hook layer enforces several constraints on test files; clean-coder produces code that satisfies these on the first write.
+
+- **Mock completeness.** When a mock object stands in for a record, populate every attribute the production code path under test reads. The `check_incomplete_mocks` hook flags mocks missing fields the assertions touch.
+- **No decorators named `skip*` on test functions.** Tests fail with a clear error rather than skip when a system dependency is missing. The hook fires on any decorator (whether `@skip_if_missing_dependency`, `@unittest.skipIf`, `@pytest.mark.skip`, or any custom variant) whose identifier contains the substring `skip`.
+- **No existence-only tests.** A test whose entire body is `assert callable(x)`, `assert hasattr(module, "name")`, or `assert obj is not None` covers no behavior. Replace with an assertion that exercises the behavior — call the function and assert on its return value or side effect.
+- **No constant-equality tests.** A test whose sole assertion is `assert CACHE_DIR == "cache"` (or any `UPPER_SNAKE == LITERAL` pattern) just verifies the constant has not changed. Delete it or replace with a behavior assertion.
+- **No tautological assertions.** `assert CONSTANT == CONSTANT` and `assert hasattr(module, "name")` pass regardless of the implementation. Replace with assertions that would fail if the implementation regressed.
+- **Test through the public API.** Do not assert on private state, hook return values, internal class fields, `_protected_field`, `__private_field`, or `component.state.X`. If the test needs visibility the public API does not provide, the public API needs a method, not the test.
+- **For React components**, query in this priority order: `getByRole > getByLabelText > getByText > getByTestId`. Use `userEvent` over `fireEvent` (more realistic). Mock at API boundaries (network calls, external services), not internal hooks or utilities.
+- **Test infrastructure stays pragmatic.** A test helper file passes when all of these hold: ONE file (not a package); only `def` functions (no class definitions); no module-level state besides one or two simple constants; no caching, no lazy initialization, no abstractions added "for future use"; imports cover the test target plus stdlib only — no helper imports another helper.
+- **E2E spec test naming.** In `*.spec.*` files, do not include `online` or `offline` substrings inside `test()`, `it()`, or `describe()` titles — file scope defines online/offline behavior. The `check_e2e_test_naming` hook fires on these substrings inside spec test titles.
+
+### Required vs optional parameters
+
+Add an optional parameter the moment a caller actually varies the value (YAGNI). When every existing call site passes the same value, make the parameter required (or inline the value as a local constant). Remove parameters that no caller passes and no body reads. The `check_unused_optional_parameters` hook fires when an optional parameter has no call site that passes a value different from the default.
+
+### Platform safety and external tools
+
+Several patterns silently fail or corrupt output on Windows or in shell/CLI integrations. Avoid each pattern when generating new code.
+
+**Windows filesystem cleanup.** When generating Python code that removes a directory tree, do not call `shutil.rmtree` with the `ignore_errors=True` keyword argument. Files carrying the `ReadOnly` attribute (any file under `.git/objects/pack/`, anything Claude Code writes under `~/.claude/teams/`) raise `PermissionError`, which the keyword silently swallows; the tree stays on disk and cleanup looks successful but removes nothing. Linux is unaffected because `unlink` only needs write on the parent directory. Use a handler that strips `S_IWRITE` and retries the failing syscall:
+
+```python
+import os
+import shutil
+import stat
+import sys
+
+
+def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def force_rmtree(target_path: str) -> None:
+    handler_kw = (
+        {"onexc": _strip_read_only_and_retry}
+        if sys.version_info >= (3, 12)
+        else {"onerror": _strip_read_only_and_retry}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+```
+
+`onexc` is Python 3.12+; `onerror` is the pre-3.12 form. `*_exc_info` collapses the signature difference between them. `removal_function` is whichever syscall the rmtree was attempting (`os.unlink` for files, `os.rmdir` for directories) — re-call it after `chmod` to finish the work that originally failed.
+
+**Windows directory creation in Node.** When generating Node code, prefer `mkdirSync(path, { recursive: true })` against any path that may already exist. Existing directories carrying the `ReadOnly` attribute raise without `recursive: true`. If a non-recursive call is intentional (you want the existence check to fail loudly), strip the attribute first via `os.chmod(path, stat.S_IWRITE)` (Python) or `(Get-Item $path -Force).Attributes = "Directory"` (PowerShell).
+
+**Windows API integer parameters.** Use `0` rather than `None` for unused integer parameters in `win32gui` calls. The `check_windows_api_none` hook fires on `win32gui.X(.., None)` patterns — the Win32 API rejects `None` for these positions.
+
+**`gh` CLI body content.** Every `gh` command that includes markdown body content uses `--body-file <path>` with a temporary file. Never pass body text via the `--body` argument or its `-b` shorthand: backticks in markdown body content are stored on GitHub as the literal string `\`` instead of rendering as code formatting. Affects: `gh issue create|edit|comment`, `gh pr create|edit|comment|review`. The `gh_body_arg_blocker.py` hook fires on the bash form.
+
 ### Test-file exemptions
 
 Tests are exempt from several gates: magic values, constants location, file-global use-count, and the new-inline-comment gate. Test-file detection covers `test_*.py`, `*_test.py`, `*.test.*`, `*.spec.*`, `conftest.py`, and any path under `/tests/`.
 
+## Files Clean-Coder Does Not Create or Edit
+
+Several file classes are blocked from edit by the `sensitive_file_protector.py` hook or are otherwise out of scope for code generation:
+
+- **Lock files.** `package-lock.json`, `yarn.lock`, `Pipfile.lock`, `poetry.lock`, `pnpm-lock.yaml`, `composer.lock`. Lock files are regenerated by their package manager, not edited by hand.
+- **Secret and credential files.** `.env`, `.env.*`, `*.env`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `credentials.json`, `secrets.json`, `id_rsa`, `id_ed25519`. The hook denies edits — values belong in environment configuration outside the repository.
+- **Scratch helper files.** Do not generate files matching `scratch_*.py`, `debug_*.py`, `try_*.py`, `repro_*.py`, or temporary log/output files (`*.log` outside `logs/`, `output_*.txt`, `dump_*.json`). Investigate in memory or via tool output instead. If the task genuinely requires a one-off script, name it after the feature it supports and remove it before the task closes.
+- **Planning and audit artifacts.** `docs/plans/*.md`, `*.plan.md`, `SESSION_STATE.md`, `*.audit.json`, `*.audit.md`, `gate_audit_report.json` and similar. Plan documents live in `~/.claude/plans/` (untracked).
+- **Image assets.** `*.png`, `*.jpg`, `*.jpeg`, `*.gif`, `*.webp`, `*.avif`, `*.svg`, `*.ico` belong in external storage, not the repository.
+
 ## Hook-Enforced Rules (pass these gates to commit your write)
 
 These gates are checked by `code_rules_enforcer.py`. Satisfying each gate lets your file write succeed.
@@ -264,6 +343,30 @@ These gates are checked by `code_rules_enforcer.py`. Satisfying each gate lets y
 | File length | Advisory at 400 lines (soft), strong nudge at 1000 — emitted to stderr; the write proceeds |
 | Magic values | Literals inside production function bodies (0, 1, -1 exempt; structural f-string fragments included) |
 | Constants location | Module-level `UPPER_SNAKE = ...` outside `config/` in production code (exempt path families listed in Inline Rule Reference) |
+| Inline literal collections | `[1, 2, 3]` / `{1, 2, 3}` of two or more constants in production function bodies |
+| Bare string structural magic | String literals matching path / URL / regex shapes outside f-strings |
+| Banned identifiers | Variable named `result`, `data`, `output`, `response`, `value`, `item`, or `temp` in production code |
+| Boolean naming | Boolean assignments lacking the `is_` / `has_` / `should_` / `can_` prefix |
+| Loop variable naming | Loop variables not in `i` / `j` / `k` / `e` and not prefixed with `each_` |
+| Collection naming | Collection assignments lacking the `all_` prefix |
+| Parameter type annotations | Function parameter without an annotation |
+| Return type annotations | Function without a declared return type |
+| `Any` / `# type: ignore` | `Any` annotations and `# type: ignore` without a trailing reason of ≥5 characters |
+| Function-local UPPER_SNAKE | Advisory — `UPPER_SNAKE_CASE = ...` inside a function body suggests a constant that should live in `config/` |
+| File-global constant use count | Module-level UPPER_SNAKE constant used by exactly one function/method |
+| Library `print()` | `print()` outside CLI markers (`/scripts/`, `_cli.py`, `/cli.py`) |
+| Unused optional parameters | Optional parameter where every call site passes the same value as the default |
+| Skip decorators on tests | Any decorator named `skip*` applied to a `test_*` function |
+| Existence-only tests | Test body whose only assertions are `callable(x)`, `hasattr(...)`, or `x is not None` |
+| Constant-equality tests | Test whose sole assertion is `UPPER_SNAKE == LITERAL` |
+| Incomplete mocks | Advisory — mock objects missing fields the production code under test reads |
+| Duplicated format patterns | Advisory — identical format-string templates at multiple call sites |
+| `win32gui` calls with `None` | `win32gui.X(.., None)` for unused integer parameters — use `0` |
+| E2E spec test names | `online` / `offline` substring in `test()` / `it()` / `describe()` titles in `*.spec.*` files |
+| mypy validation | `mypy_validator.py` runs at write time — type errors block the write |
+| Sensitive files | Edits to `.env*`, `*.pem`, `*.key`, lock files, etc. (`sensitive_file_protector.py`) |
+| Windows-unsafe rmtree | The `shutil.rmtree` call with `ignore_errors=True` (`windows_rmtree_blocker.py`) |
+| `gh` body argument | `gh ... --body "..."` in shell calls — must use `--body-file` (`gh_body_arg_blocker.py`) |
 
 ## Code Generation Checklist (the first-attempt-quality evaluator)
 
@@ -340,12 +443,17 @@ Every line you write or modify will:
 - Satisfy every hook-enforced gate so each write succeeds on the first attempt
 - Return CLEAN from `/check`, `/review-code`, and `/readability-review`
 - Use complete type hints on every parameter and return
+- Pass `mypy_validator.py` cleanly — every file is mypy-clean at write time
+- Land in the format the project's `auto_formatter.py` produces — the formatter runs at write time, but generation should already match the canonical Black/Prettier output
+- Carry no `Any` annotations and no `# type: ignore` without a ≥5-character trailing reason
 - Pull every literal into a named constant (with the documented 0, 1, -1 exemptions)
 - Use full words throughout (every abbreviation expanded)
 - Self-document through naming alone (zero new inline comments)
 - Use guard clauses and early returns in place of every `else` block
 - Stay under 15 lines per function
 - Import constants from centralized config (or module-level for hooks)
+- Avoid platform pitfalls — no `shutil.rmtree` with `ignore_errors=True`, no `mkdirSync` against a possibly-existing path without `{ recursive: true }`, no `gh ... --body "..."` in shell calls
+- Avoid generating sensitive files, lock files, or scratch helpers (see "Files Clean-Coder Does Not Create or Edit")
 
 These standards apply to YOUR code — lines you add or change. Untouched code in the same file stays out of scope unless the task explicitly extends it.
 

package/bin/install.mjs

@@ -16,7 +16,7 @@ const PACKAGE_NAME = 'claude-dev-env';
 const PACKAGE_VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
 const packageRequire = createRequire(import.meta.url);
 
-const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts'];
+export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents', 'system-prompts', 'scripts', '_shared'];
 
 export function collectPackageSourceConflicts(packageDirectory) {
     const gitConflictStatusCodes = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
@@ -289,7 +289,17 @@ function writeManifest(installedFiles) {
     writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2) + '\n');
 }
 
-function install(selectedGroups) {
+function install(selectedGroups, options = {}) {
+    const isUpdateRefresh = Boolean(options.isUpdateRefresh);
+    if (isUpdateRefresh && !selectedGroups && existsSync(MANIFEST_FILE)) {
+        console.log(
+            `${PACKAGE_NAME}: --update — removing prior managed files under ${CLAUDE_HOME}, then reinstalling from the package.\n`,
+        );
+        purgeManagedInstallation({ requireManifest: false });
+    } else if (isUpdateRefresh) {
+        const installScope = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'full';
+        console.log(`${PACKAGE_NAME}: --update — re-running ${installScope} install into ${CLAUDE_HOME}\n`);
+    }
     const groupLabel = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'all';
     console.log(`\nInstalling ${PACKAGE_NAME} (${groupLabel})...\n`);
     abortWhenPackageSourceHasConflicts(PACKAGE_ROOT);
@@ -534,11 +544,13 @@ function unsetGlobalGitHooksPathIfOurs() {
 }
 
 
-function uninstall() {
-    console.log(`\nUninstalling ${PACKAGE_NAME}...\n`);
+function purgeManagedInstallation({ requireManifest }) {
     if (!existsSync(MANIFEST_FILE)) {
-        console.error('No installation manifest found. Nothing to uninstall.');
-        process.exit(1);
+        if (requireManifest) {
+            console.error('No installation manifest found. Nothing to uninstall.');
+            process.exit(1);
+        }
+        return 0;
     }
     const manifest = JSON.parse(readFileSync(MANIFEST_FILE, 'utf8'));
     let removed = 0;
@@ -581,12 +593,18 @@ function uninstall() {
     console.log(`\nRemoved ${removed} files.\n`);
 }
 
+function uninstall() {
+    console.log(`\nUninstalling ${PACKAGE_NAME}...\n`);
+    purgeManagedInstallation({ requireManifest: true });
+}
+
 function printHelp() {
     console.log(`
 ${PACKAGE_NAME} - Claude Code development standards installer
 
 Usage:
   npx ${PACKAGE_NAME}              Install everything
+  npx ${PACKAGE_NAME} --update     Full install: remove prior manifest-tracked files first, then reinstall
   npx ${PACKAGE_NAME} --only X     Install specific groups
   npx ${PACKAGE_NAME} --uninstall  Remove installed files
   npx ${PACKAGE_NAME} --help       Show this help
@@ -608,7 +626,9 @@ writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak firs
 `);
 }
 
-const args = process.argv.slice(2);
+const rawArgs = process.argv.slice(2);
+const args = rawArgs.filter((flag) => flag !== '--update');
+const isUpdateRefresh = rawArgs.includes('--update');
 if (args.includes('--help') || args.includes('-h')) {
     printHelp();
 } else if (args.includes('--uninstall')) {
@@ -629,5 +649,5 @@ if (args.includes('--help') || args.includes('-h')) {
             process.exit(1);
         }
     }
-    install(selectedGroups);
+    install(selectedGroups, { isUpdateRefresh });
 }

package/bin/install.test.mjs

@@ -5,7 +5,7 @@ import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { collectPackageSourceConflicts } from './install.mjs';
+import { collectPackageSourceConflicts, CONTENT_DIRECTORIES } from './install.mjs';
 
 
 function createTemporaryGitRepository() {
@@ -127,6 +127,14 @@ test('collectPackageSourceConflicts returns empty when directory is not inside a
 });
 
 
+test('CONTENT_DIRECTORIES includes _shared so installer copies _shared/pr-loop/ to ~/.claude/_shared/', () => {
+    assert.ok(
+        CONTENT_DIRECTORIES.includes('_shared'),
+        '_shared must be in CONTENT_DIRECTORIES so the installer copies _shared/pr-loop/ alongside skills/',
+    );
+});
+
+
 test('collectPackageSourceConflicts surfaces both-added and deleted-by-them entries', () => {
     const repositoryRoot = createTemporaryGitRepository();
     try {

package/docs/CODE_RULES.md

@@ -49,6 +49,9 @@ These rules are automatically enforced by `code_rules_enforcer.py`. Violations b
 | File line count | Advisory only — see [File length guidance](#65-file-length-guidance) |
 | Magic values | No literals in production function bodies (0, 1, -1 exempt). **Test files exempt.** Includes string templates — if you strip the interpolations from an f-string and the remaining literal text is structural (paths, URLs, patterns), those fragments are magic values that belong in config |
 | Constants location | No `UPPER_SNAKE =` outside `config/` in **production code**. **Test files may define local constants.** |
+| Hardcoded user paths | No string literals naming a specific user's home directory in production code (`C:/Users/jon/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()` or `os.path.expanduser('~')`. **Exempt:** test files, `config/` files, workflow registry paths (`/workflow/`, `_tab.py`, `/states.py`, `/modules.py`), Django migrations (`/migrations/`), and hook infrastructure (the enforcer embeds path patterns and must not self-block). |
+| sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (or equivalent membership test) so reloads do not push the same entry repeatedly. **Test files exempt.** |
+| Unused module-level imports | Module-level imports never referenced in the file body are flagged. Skipped for files declaring `__all__` (re-exports), files using `TYPE_CHECKING` (annotation-only imports), and lines marked `# noqa`. **Test files exempt.** |
 
 ### Where UPPER_SNAKE is allowed
 

package/docs/agents-md-alignment-plan.md

@@ -0,0 +1,123 @@
+# AGENTS.md Alignment Plan
+
+This document captures the alignment between `AGENTS.md` (the canonical code-rules instruction set consumed by Cursor BugBot, Copilot, Claude, and other code-review/authoring agents) and the local enforcement layer (`code_rules_enforcer.py` and companion blocking hooks).
+
+## Goal
+
+Two-way alignment:
+
+1. Every rule the hooks enforce at write time is documented in `AGENTS.md` so review tools without hook access (Cursor BugBot, Copilot, external reviewers) flag the same violations from the diff alone.
+2. Every rule `AGENTS.md` requires is either (a) enforced by a hook at write time, (b) explicitly listed as bugbot-only judgment because it requires diff-semantic reasoning, or (c) a candidate for a future hook.
+
+This file is the single source of truth for the alignment status.
+
+## Methodology
+
+- Read every `check_*` function in `packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py` (28 functions, lines 108–2236) plus the `validate_content` dispatch (line 2239).
+- Read every Write/Edit hook registered in `packages/claude-dev-env/hooks/hooks.json`.
+- Read `packages/claude-dev-env/hooks/blocking/sensitive_file_protector.py` for file-level blocks.
+- Read every rule file in `~/.claude/rules/*.md` and the canonical CODE_RULES.md files in this repo.
+- Walked `AGENTS.md` bullet by bullet against the above.
+
+## What this PR changes
+
+### Added to `AGENTS.md`
+
+- Intro pointer to the new **Hook enforcement** appendix.
+- **Magic values & configuration**: explicit config-domain table (`config/timing.py` for timing values, `config/constants.py` for ports/URLs/thresholds, `config/selectors.py` for DOM locators) and a flag rule for new constants whose value or semantic name already exists in `config/`.
+- **Design**: tightened the YAGNI bullet to specify "every existing call site passes the same value → required (or inline)".
+- **Tests**: five new bullets — delete-no-value tests, fail-not-skip rule, pragmatic-infra five-point checklist, public-API-only assertions, React query priority and `userEvent`/API-boundary mocking.
+- **Platform and tooling**: the unsafe-`rmtree`-on-Windows pattern is blocked (with the canonical `force_rmtree` helper inlined), Node `mkdirSync` requires `{ recursive: true }` on possibly-existing paths, and all `gh` commands with markdown body content must use `--body-file`.
+- **Repo hygiene**: never-commit list (`docs/plans/*.md`, `*.plan.md`, `SESSION_STATE.md`, `*.audit.json`, `*.audit.md`, image extensions) and a scratch-file pattern enumeration.
+- **Hook enforcement** appendix mapping each hook-enforced rule to its enforcing hook file.
+
+### Deliberately excluded
+
+PR draft lifecycle bullets and one-commit-per-review-stage rules were proposed and then removed. Cursor BugBot reviews diffs and PR descriptions; it cannot toggle PR ready/draft state or enforce commit-stage discipline. Those rules belong in human-facing workflow documentation, not in `AGENTS.md`.
+
+## Open items
+
+The following are documented gaps. None are addressed in this PR.
+
+### Category A — enforced locally, not yet in AGENTS.md
+
+Each closure is concrete and additive — recommended for a follow-up PR titled `docs(agents): close remaining hook-vs-rule gaps`.
+
+| ID | Hook check (file:line) | Gap |
+|---|---|---|
+| A1 | `code_rules_enforcer.py:404` `check_windows_api_none` | `win32gui.X(.., None)` — use `0` for unused int params |
+| A2 | `code_rules_enforcer.py:603` `check_e2e_test_naming` | `online`/`offline` in `test()`/`it()`/`describe()` titles in `*.spec.*` files |
+| A3 | `code_rules_enforcer.py:713` `check_type_escape_hatches` | `# type: ignore` requires trailing `# <reason>` of ≥5 chars |
+| A4 | `code_rules_enforcer.py:2126` `check_inline_literal_collections` | inline `[...]` / `{...}` of constants in production function bodies |
+| A5 | `code_rules_enforcer.py:2085` `check_string_literal_magic` | bare string literals (not just f-string fragments) matching path / URL / regex shape |
+| A6 | `code_rules_enforcer.py:843` `check_constants_outside_config_advisory` | function-local `UPPER_SNAKE = ...` advisory |
+| A7 | `code_rules_enforcer.py:2003` `check_library_print` | `print()` outside CLI markers (`/scripts/`, `_cli.py`, `/cli.py`) |
+| A8 | `sensitive_file_protector.py` | edits to `package-lock.json`, `yarn.lock`, `Pipfile.lock`, `poetry.lock`, `pnpm-lock.yaml`, `composer.lock` |
+| A9 | `sensitive_file_protector.py` | edits to `.env*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `credentials.json`, `secrets.json`, `id_rsa`, `id_ed25519` |
+| A10 | `code_rules_enforcer.py:1175` `check_existence_check_tests` | `x is not None` as sole-assertion form (currently `AGENTS.md` lists only `callable` and `hasattr`) |
+| A11 | `code_rules_enforcer.py:1839` `check_unused_optional_parameters` | the exact trigger: optional param where every call site passes the same value |
+| A12 | `mypy_validator.py` | mypy-clean is required at write time |
+| A13 | `auto_formatter.py` | auto-formatter runs on Write/Edit |
+| A14 | `code_rules_enforcer.py:1072` `check_skip_decorators_in_tests` | the broader rule is "any decorator named `skip*`", not just `@skip_if_missing_dependency` |
+| A15 | `code_rules_enforcer.py:1786` `check_duplicated_format_patterns` | identical format-string patterns at multiple call sites |
+
+### Category B — required by AGENTS.md, no local hook (bugbot-only judgment)
+
+These are reviewable from a diff but not amenable to AST/regex enforcement; they remain bugbot's judgment.
+
+- **Naming**: `ctx`/`cfg`/`msg`/`btn`/`idx`/`cnt`/`elem`/`val`/`tmp` abbreviation expansion (B1); `X_by_Y` map naming (B2); preposition parameter prefixes (B3); banned function-name prefixes `handle_`/`process_`/`manage_`/`do_` (B4); component naming for what they ARE (B5).
+- **Structure**: function length ≤ 30 lines (B6); two blank lines between Python top-level functions (B7).
+- **Types**: concrete type captures actual shape, even when bare `object` would compile (B8).
+- **Architecture**: functions vs classes vs ABCs (B9); SOLID S/O/L/I/D (B10); construction logic in models/services (B11); self-contained components (B12); `TODO:` on scaffolding (B14).
+- **Data flow**: reuse data already in scope (B13); reuse-before-create semantic duplication (B23).
+- **Tests**: pragmatic-infra five-point checklist (B15); test through public API (B16); React query priority and mocking strategy (B17).
+- **Platform**: Node `mkdirSync({recursive: true})` (B18) — Python `shutil.rmtree` is hooked, Node equivalent is not.
+- **Hygiene**: planning/image file globs (B19); scratch-file patterns (B20); PR-description references for kept files (B21).
+- **Config**: domain placement within `config/` (B22); 0-reference dead-code constants (B24).
+
+### Category C — JS/TS asymmetry
+
+`code_rules_enforcer.py` `validate_content` (line 2239) dispatches on file extension. For `.js`/`.ts`/`.tsx`/`.jsx`, only three checks run:
+
+- `check_comment_changes` — added inline / removed existing comments.
+- `check_e2e_test_naming` — online/offline in spec test titles.
+- `advise_file_line_count` — advisory.
+
+Every other rule (magic values, constants location, banned identifiers, type annotations, boolean naming, loop variable naming, parameter annotations, return annotations, library print, optional-param-unused, `Any` detection) runs on Python files only. For JS/TS code, `AGENTS.md` is the only enforcement layer — bugbot review is the gate.
+
+Whether each Python check has a JS/TS equivalent that ports cleanly: not investigated. Out of scope for this PR.
+
+## Recommended hook additions
+
+Not part of this PR — proposed as separate small PRs (one new check + tests per PR, following the existing `test_code_rules_enforcer_*.py` pattern). Each is AST/regex-tractable.
+
+| Item | Suggested check | Note |
+|---|---|---|
+| B1 | extend `BANNED_IDENTIFIERS` | add `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp` |
+| B2 | dict-target naming rule | flag dict assignments whose target name lacks `_by_` |
+| B3 | parameter-name prefix rule | flag direction parameters lacking `from_`/`to_`/`into_` |
+| B4 | banned function-name prefixes | flag `def handle_*`, `def process_*`, `def manage_*`, `def do_*` |
+| B6 | function-length advisory | per-function line count, advisory above 30 |
+| B19 | extend `sensitive_file_protector.py` | block edits to `*.plan.md`, `SESSION_STATE.md`, `docs/plans/*.md`, `*.audit.{json,md}`, image extensions |
+| B20 | scratch-file name patterns | block edits to `scratch_*.py`, `debug_*.py`, `try_*.py`, `repro_*.py` |
+| B22 | config-domain placement | flag a constant added to `config/constants.py` whose name suggests `timing.py` or `selectors.py` |
+| B24 | 0-reference dead-code constants | extend `check_file_global_constants_use_count` to also flag 0 callers |
+
+## Files in this PR
+
+- `AGENTS.md` (modified) — adds the rules and sections listed above.
+- `packages/claude-dev-env/docs/agents-md-alignment-plan.md` (new) — this document.
+
+## Verification
+
+- Read updated `AGENTS.md` end-to-end and confirm each new bullet lives under the correct section heading.
+- Confirm no rule mentioned in the **Hook enforcement** appendix is missing its source check in `code_rules_enforcer.py` or sibling hook file.
+- Confirm the canonical `force_rmtree` helper code block in **Platform and tooling** describes the rule without containing the exact match-string the `windows_rmtree_blocker.py` hook scans for. Otherwise the hook will block any future edit to the file.
+- No code changes — the `AGENTS.md` and plan doc are documentation only.
+
+## Out of scope
+
+- Closing the Category A gaps in `AGENTS.md` (tracked above; recommended follow-up PR).
+- Implementing any of the Category B hook additions (each is its own small PR).
+- Investigating JS/TS hook coverage parity (Category C).
+- Changes to `code_rules_enforcer.py` or any other hook source file.