claude-dev-env 2.28.1 → 2.29.0

package/hooks/blocking/claude_md_orphan_file_blocker_parts/AGENTS.md

@@ -1,28 +1 @@
-# claude_md_orphan_file_blocker_parts
 
-The concern modules `claude_md_orphan_file_blocker.py` wires together to block a
-per-directory `CLAUDE.md` that names a file absent from its subtree. The entry
-hook imports them and re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `references.py` | Extracts the bare filenames a table cell names and the scripts a fenced run command invokes, honoring the `../` relative-path exemptions |
-| `subtree_scan.py` | Resolves the scan root and reports which referenced filenames are absent from it, with a bounded walk plus a direct probe fallback |
-| `scan_plan.py` | Builds the Write/Edit/MultiEdit scan plan and collects the orphan filenames the change introduces, excluding pre-existing orphans |
-| `decision.py` | Builds the deny payload listing the missing files and closing with the retry hint, and emits the decision JSON |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The region-join newline, the retry hint the deny reason closes with, and the missing-name join separator (`orphan_blocker_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/
-```

package/hooks/blocking/config/AGENTS.md

@@ -1,10 +1 @@
-# hooks/blocking/config
 
-A Python package that holds shared constants for blocking hooks. Opinionated prose-style gates import from here.
-
-## Key files
-
-| File | Contents |
-|---|---|
-| `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
-| `prose_style_enforcement_constants.py` | `CLAUDE_PROSE_STYLE_ENFORCEMENT` opt-in (default off) for opinionated prose gates |

package/hooks/blocking/inventory_intent_records/AGENTS.md

@@ -1,26 +1 @@
-# inventory_intent_records
 
-The shared pending-intent store that lets `package_inventory_stale_blocker.py`
-and `claude_md_orphan_file_blocker.py` add a new file and its inventory row in
-one change, in either order. When one blocker denies, it records a note; the
-sibling blocker reads that note to allow the matching second write.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `records.py` | Read, record, peek, and consume the per-session file and row intents; a missing or corrupt store reads as no notes |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The records-file name shape, the freshness window, the list keys, and the note field names (`intent_records_constants.py`) |
-| `tests/` | pytest suite for the records store |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/inventory_intent_records/tests/
-```

package/hooks/blocking/package_inventory_stale_blocker_parts/AGENTS.md

@@ -1,26 +1 @@
-# package_inventory_stale_blocker_parts
 
-The concern modules `package_inventory_stale_blocker.py` wires together to block a
-new production file its package inventory omits. The entry hook imports them and
-re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `inventory_detection.py` | Surveys a directory's `README.md`/`CLAUDE.md`/`SKILL.md`, collects the filenames they name, and reports whether a maintained inventory omits the file being written |
-| `decision.py` | Builds the deny payload naming the omitted file and closing with the retry hint, and emits the decision JSON |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The retry hint the deny reason closes with and the inventory-name join separator (`inventory_blocker_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/package_inventory_stale_blocker_parts/tests/
-```

package/hooks/blocking/pii_prevention_blocker_parts/AGENTS.md

@@ -1,24 +1 @@
-# pii_prevention_blocker_parts
 
-The concern modules `pii_prevention_blocker.py` wires together. The entry hook
-imports them and re-exports their surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `repository_exemption.py` | Resolves a commit's origin owner/repo slug, decides whether the repository skips the staged PII scan, and resolves the exact values that repository allows past the scan |
-| `repository_resolution.py` | Reads the repository a commit command targets — composing multiple `-C` values and a leading `cd`/`pushd` — and builds the deny reason naming the path when the repository root does not resolve |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The repository-resolution deny-message template and the session-cwd label (`repository_resolution_constants.py`) |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tests/
-```

package/hooks/blocking/tdd_enforcer_parts/AGENTS.md

@@ -1,30 +1 @@
-# tdd_enforcer_parts
 
-The concern modules `tdd_enforcer.py` wires together to run the TDD gate. Each
-module owns one concern; the entry hook imports them and re-exports their
-surface for the test suite.
-
-## Modules
-
-| File | Purpose |
-|---|---|
-| `path_classification.py` | Classifies a write target (docs, tests, `.claude` trees) the gate skips, and extracts the written text from a Write, Edit, or MultiEdit payload |
-| `content_analysis.py` | Decides whether a payload is constants-only, and whether an Edit or MultiEdit merely removes or reorders imports |
-| `candidate_paths.py` | Resolves the candidate test files whose freshness can satisfy the gate for a production file |
-| `freshness.py` | Checks whether a candidate test was modified within the window and holds a real test function |
-| `git_tracking.py` | Detects a write that restores a git-tracked file absent on disk, so a remove-then-Write rewrite is exempt from the gate |
-| `decisions.py` | Builds the deny reason and writes the allow or deny decision JSON to stdout |
-| `__init__.py` | Package marker |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `config/` | The freshness window, the ancestor-walk limit, the git-tracking command tokens, the source-file extension sets, and the join separator (`tdd_enforcer_constants.py`) |
-| `tests/` | pytest suite with one test module per module above |
-
-## Running tests
-
-```bash
-python -m pytest packages/claude-dev-env/hooks/blocking/tdd_enforcer_parts/tests/
-```

package/hooks/git-hooks/AGENTS.md

@@ -1,32 +1 @@
-# hooks/git-hooks
 
-Native git hooks that run outside the Claude Code lifecycle — invoked directly by git at commit and push time. The installer copies these scripts into the user's shared git-hooks directory (`core.hooksPath`).
-
-## Key files
-
-| File | Git hook | What it does |
-|---|---|---|
-| `pre_commit.py` | `pre-commit` | Runs immediate CODE_RULES and terminology validation over staged changes; exits 1 when any staged file has a blocking violation. CI runs package tests for package Python changes. |
-| `pre_push.py` | `pre-push` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate. An existing branch's gate base is the merge base with the remote default branch; the gate process still diffs that base against checkout HEAD, so the surface matches the pushed tip only when HEAD is that tip. |
-| `pre_push_base_reference.py` | — | Resolves a usable gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then turns a symbolic default-branch head into a reference that git can resolve |
-| `post_commit.py` | `post-commit` | Runs bookkeeping, then best-effort reminds the agent about its PR |
-| `pull_request_handoff.py` | — | Prints the full PR title and description handoff prompt |
-| `gate_utils.py` | — | Shared helpers: resolves the gate script path, checks that the path is a safe regular file |
-| `test_config.py` | — | Test configuration helpers |
-| `test_gate_utils.py` | — | Tests for `gate_utils.py` |
-| `test_pre_commit.py` | — | Tests for `pre_commit.py` |
-| `test_pre_push.py` | — | Tests for `pre_push.py` |
-| `test_pre_push_base_reference.py` | — | Tests for the gate base resolution in `pre_push.py` |
-| `conftest.py` | — | Puts this directory on `sys.path` and clears cached `config` modules, so each test module imports the hooks at the top of the file |
-
-## Subdirectory
-
-| Directory | Role |
-|---|---|
-| `git_hooks_constants/` | Shared constants imported by the git-hook scripts |
-
-## Conventions
-
-- The installer strips the `_` and `.py` suffix when copying into the live git-hooks path (e.g. `pre_commit.py` becomes `pre-commit`).
-- Constants (exit codes, argument names, error messages) live in `git_hooks_constants/` and are imported at the top of each script.
-- Run tests with `python -m pytest git-hooks/test_<name>.py`.

package/hooks/git-hooks/git_hooks_constants/AGENTS.md

@@ -1,21 +1 @@
-# hooks/git-hooks/git_hooks_constants
 
-Shared constants imported by the git-hook scripts in `git-hooks/`. Centralizes exit codes, argument names, and error messages so every tunable lives in one place.
-
-## Files
-
-| File | Contents |
-|---|---|
-| `__init__.py` | Exports all constants; marks this as a package so `from git_hooks_constants import ...` resolves |
-
-## Key constants (defined in `__init__.py`)
-
-- `GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE` — exit code when the gate script cannot be found or launched
-- `GATE_SCRIPT_NOT_FOUND_MESSAGE` — error message when the gate script path does not exist
-- `INVOKE_GATE_FAILURE_MESSAGE` — error message when the gate subprocess fails to start
-- `STAGED_SCOPE_ARGUMENT` — CLI argument passed to the gate script to scope it to staged changes
-
-## Conventions
-
-- Import with `from git_hooks_constants import <CONSTANT>` from within the `git-hooks/` directory.
-- Add new constants here rather than inline in the hook scripts.

package/hooks/hooks_constants/AGENTS.md

@@ -1,100 +1 @@
-# hooks/hooks_constants
 
-Shared constant modules imported by hooks throughout the `hooks/` tree. Each file holds the tunables for one hook or one cross-cutting concern, keeping magic values out of the hook scripts themselves.
-
-## Files
-
-| File | What it holds |
-|---|---|
-| `__init__.py` | Package marker (`# pragma: no-tdd-gate`) |
-| `any_type_config.py` | Config for the `Any`-type escape-hatch check |
-| `ask_user_question_shape.py` | Pure AskUserQuestion lean-block shape analyzer: grades question and option-description prose against shared chat-detail markers and sentence/word caps with no hook I/O |
-| `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
-| `bash_pre_tool_use_dispatcher_constants.py` | Permission outcomes, tool-name sets, and the ordered hosted-hook roster for the Bash PreToolUse dispatcher (also covers PowerShell-shared gates) |
-| `pre_tool_use_dispatcher_constants.py` | Shared Write, Edit, and MultiEdit tool-name set and the ordered hosted-hook roster for the Write/Edit/MultiEdit PreToolUse dispatcher |
-| `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
-| `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
-| `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
-| `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
-| `enter_worktree_prefetch_constants.py` | Tool name, origin-remote ref names, and git-command timeouts for the EnterWorktree origin-prefetch hook |
-| `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
-| `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
-| `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
-| `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
-| `cursor_cli_python_misfire_blocker_constants.py` | Detection patterns and deny message for Cursor launches that mistreat a Python code-rules-gate script |
-| `destructive_command_environment_constants.py` | Environment keys and shared truthy values used by destructive-command hooks |
-| `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
-| `docstring_rule_gate_count_blocker_constants.py` | Target rule basename, spelled-out-number lookup, count-clause and `check_*` validator patterns, and block-message text for the docstring-rule gate-count staleness blocker |
-| `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
-| `duplicate_rmtree_helper_blocker_constants.py` | Sanctioned Windows-safe rmtree helper names, the definition pattern, and the exempt-path set for the duplicate-rmtree-helper blocker |
-| `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
-| `fable_spawn_gate_constants.py` | The spawn tool-name set, the fable model alias and the model-id segment split pattern, the `FABLE-SPAWN-AUTHORIZED` authorization token, the advisor-protocol document path, payload field names, the deny message, and the deny `additionalContext` recovery text for the fable-tier spawn gate |
-| `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
-| `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
-| `harness_scratchpad_constants.py` | Fixed path components (`claude` / `claude-` user-directory name and prefix, `scratchpad` leaf name), the PreToolUse session-id payload key, and the `CLAUDE_CODE_SESSION_ID` environment variable name that the code-rules and TDD gates use to recognize an existing harness session scratchpad directory |
-| `hook_block_logger.py` | `log_hook_block()` — shared fail-safe logger every blocking hook calls to append a JSON record of each block decision to `~/.claude/logs/hook-blocks.log` |
-| `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
-| `hosted_hook_runner.py` | `run_hook_capturing_output()` — shared runner that runs one dispatcher-hosted hook in-process via runpy and returns its captured stdout and crash flag |
-| `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
-| `js_conventions_constants.py` | Banned identifier set, boolean-prefix pattern, and declaration/JSDoc patterns for the JavaScript convention checks |
-| `local_identity.py` | Loader for local machine values: NAS host, ssh user, and ssh port the ssh enforcer guards (`CLAUDE_NAS_*` / `~/.claude/local-identity.json` with placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`, keyed by owner/repo slug) read from the git-ignored local file whose path `CLAUDE_LOCAL_IDENTITY_PATH` may point elsewhere; also composes the ssh enforcer's two deny messages that quote the NAS values |
-| `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
-| `multi_edit_reconstruction.py` | `apply_edits()` / `edits_for_tool()` — shared helpers that reconstruct the post-edit content of an Edit or MultiEdit, imported by the blockers that judge post-edit content |
-| `mypy_integration_constants.py` | Path markers (``.git``, ``.py``, ``pyproject.toml``) for mypy project-root resolution, plus detached-file `--follow-imports=skip` flags, subprocess timeout, and timeout skip message |
-| `mypy_validator_cache_constants.py` | Cache paths and tunables for the mypy_validator per-session caches |
-| `nas_ssh_binary_enforcer_constants.py` | Bash tool name, ssh-family basenames, OpenSSH binary path suffixes, and the batch-mode pattern for the NAS ssh binary enforcer; segment helpers come from `shell_command_segments.py` |
-| `open_questions_in_plans_blocker_constants.py` | Patterns for detecting unresolved open questions in plan documents |
-| `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
-| `package_inventory_stale_blocker_constants.py` | Inventory document names, production code extensions, backtick token pattern, smallest inventory size, exempt names, scan budget, and block-message text for the package-inventory stale-entry blocker |
-| `paired_test_coverage_constants.py` | Test-directory name, stem-test filename affixes, test-file globs, exempt public-function names, scan budget, coverage threshold, and guidance text for the public-function paired-test coverage check |
-| `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
-| `pii_prevention_constants.py` | Patterns, allowlists, path exemptions, and deny-message text for `pii_prevention_blocker` |
-| `piped_pytest_blocker_constants.py` | Bash tool name, pytest program basenames and the python-interpreter basename pattern, the pipe and segment-reset operator token sets, and the deny message for the piped-pytest blocker; classification that consumes those program and wrapper constants lives in `pytest_invocation.py` |
-| `pytest_invocation.py` | Pure parsed-segment classifier for pytest runs through interpreters, shims, wrappers, and shell string-exec forms; no pipeline deny decision |
-| `prose_matcher_precision_constants.py` | Sample floor, keep/narrow precision floors, matcher ids, label decisions, advisory log path, emit caps, and context fingerprint length for OP-07B prose-matcher advisory telemetry |
-| `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
-| `precommit_code_rules_gate_constants.py` | Git-repository-root resolution command and timeout for the `precommit_code_rules_gate` library module |
-| project_paths_reader.py | Loads ~/.claude/project-paths.json and finds a home-bounded git root for registry checks |
-| `pyproject_config_discovery_constants.py` | Table names (``tool`` key, ``mypy``, ``ruff``) for resolving a validator's config from a pyproject.toml `[tool.<name>]` table |
-| `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
-| `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
-| `ruff_integration_constants.py` | ``NO_COLOR`` / ``FORCE_COLOR`` environment variable names for plain ruff diagnostics |
-| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the `Invoke-Item` block message for the open-locally attach blocker |
-| `sensitive_file_protector_constants.py` | Sensitive filename patterns, committed-template suffixes that earn an exemption, and the deny decision and message template for `sensitive_file_protector` |
-| `session_edit_stage_gate_constants.py` | Tracker filename prefix/suffix, JSON payload key, edit tool name set, session-id sanitize pattern, lock filename suffix and lock-acquire timing, git diff command, commit flag escapes, and deny-message template shared by the session edit stage gate trio |
-| `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
-| `session_start_injector.py` | Pure SessionStart context injector: normalize `source` (`startup`/`resume`/`clear`/`compact`), honor enable/timeout, return structured injection results for starter hooks |
-| `session_start_injector_constants.py` | Known SessionStart source values, injection status codes, enable env var, default timeout for the shared injector |
-| `test_session_start_injector.py` | Behavioral tests for every known source, disabled, timeout, and unknown-source paths |
-| `orchestrator_auto_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the orchestrator auto-starter |
-| `issue_tracker_session_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the repository-gated issue-tracker starter |
-| `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
-| `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |
-| `shell_command_pipeline.py` | Quote-aware shell pipeline parsing: operator-paired segments after line-continuation join, comment strip, heredoc body drop, and parenthesis-group join |
-| `shell_command_segments.py` | Shell tokenization helpers shared by the segment-walking blockers: segment splitting on control operators, a segment's effective leading program, and a token's basename |
-| `shell_substitution_blocker_constants.py` | Tool name, payload keys, the four substitution-detection patterns, the deny decision shape, and the corrective message for the shell-substitution blocker |
-| `stale_comment_reference_blocker_constants.py` | Identifier pattern, comment stopwords, and denial text for the stale-comment-reference blocker |
-| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects, plus the docstring-extraction and mention-span patterns for its Python docstring scan |
-| `stop_dispatcher_constants.py` | Ordered hosted-hook roster and Stop block payload field names for the Stop-chain dispatcher |
-| `style_reminder_prompt_constants.py` | The style reminder text ("small words. few words. always. forever.") for the style_reminder_prompt hook |
-| `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
-| `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
-| `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |
-| `sys_path_insert_constants.py` | Patterns for detecting unguarded `sys.path.insert` calls |
-| `task_list_loop_starter_constants.py` | The one-line task-list instruction and the full session-start directive text for the task-list loop starter hook |
-| `test_layout_constants.py` | The named constants for the test-layout write-time checks |
-| `text_stripping.py` | `strip_code_and_quotes()` — shared helper that removes fenced code blocks, inline code, and blockquotes from prose, imported by the Stop-hook prose blockers |
-| `unscoped_search_blocker_constants.py` | Tool names, `find` and listing program basenames, Get-ChildItem option sets, unscoped-root patterns, the flag/value token stride, and the deny message for the unscoped-search blocker |
-| `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
-| `volatile_path_in_post_blocker_constants.py` | Volatile path markers, affected `gh` post subcommands, MCP body param names, and the corrective message for the volatile-path post blocker |
-| `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
-| `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
-| `working_style_prompt_constants.py` | The fixed multi-paragraph working-style prompt text for the SessionStart working_style_prompt hook |
-
-## Conventions
-
-- Most files in this package are pure constants modules — no side effects, no I/O.
-- Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
-- Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
-- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, `hosted_hook_runner.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they hold logic shared across hook surfaces.
-- `local_identity.py` is a loader: it reads the environment or `~/.claude/local-identity.json` (its path overridable via `CLAUDE_LOCAL_IDENTITY_PATH`) to resolve private NAS values (with committed placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`).

package/hooks/lifecycle/AGENTS.md

@@ -1,18 +1 @@
-# hooks/lifecycle
 
-Hooks that run at session or config-change boundaries rather than on individual tool calls.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `config_change_guard.py` | PostToolUse (Write/Edit on `settings.json`) | Counts hooks in the edited `settings.json` and logs any change to `~/.claude/cache/config-change-audit.log`; alerts when the hook count drops below the last known value |
-| `enter_worktree_origin_prefetch.py` | PreToolUse (EnterWorktree) | Fetches origin's default branch before a worktree creation call, keeping the `refs/remotes/origin/<default-branch>` ref that `fresh` mode reads current; never blocks on fetch failure |
-| `session_end_cleanup.py` | SessionEnd | Purges stale cache entries from `~/.claude/cache/` (entries older than the configured threshold) and old backup files |
-| `test_config_change_guard.py` | — | Tests for `config_change_guard.py` |
-| `test_enter_worktree_origin_prefetch.py` | — | Tests for `enter_worktree_origin_prefetch.py` |
-
-## Conventions
-
-- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file, EnterWorktree prefetch tuning) live in `hooks_constants/session_env_cleanup_constants.py` and `hooks_constants/enter_worktree_prefetch_constants.py`.
-- Tests run with `python -m pytest lifecycle/test_<name>.py`.

package/hooks/observability/AGENTS.md

@@ -1,20 +1 @@
-# hooks/observability
 
-PostToolUse hooks that record agent behavior for later review. These hooks do not block tool calls; they log or annotate them.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `instructions_loaded_logger.py` | PostToolUse (file load events) | Appends a JSONL record to `~/.claude/logs/instructions_loaded.jsonl` each time Claude Code loads a context file (CLAUDE.md, rules, skills), capturing the file path, load reason, memory type, and session ID |
-| `session_file_edit_tracker.py` | PostToolUse (Write/Edit/MultiEdit) | Records the resolved absolute path of each file edited this session into a per-session JSON file under the system temp directory, for the session edit stage gate to read at commit time |
-| `prose_matcher_advisory.py` | Advisory emit from prose matchers | Privacy-safe JSONL candidates (`matcher_id`, surface, context fingerprint, label) plus keep/narrow/drop/advisory classification against the sample floor |
-| `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
-| `test_session_file_edit_tracker.py` | — | Tests for `session_file_edit_tracker.py` |
-| `test_prose_matcher_advisory.py` | — | Tests for advisory emit and precision classification |
-
-## Conventions
-
-- The log file is append-only; the hook creates the parent directory if needed.
-- Errors during logging are caught and written as error records rather than propagated — the hook never blocks the tool call.
-- Tests run with `python -m pytest observability/test_instructions_loaded_logger.py`.

package/hooks/session/AGENTS.md

@@ -1,38 +1 @@
-# hooks/session
 
-SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown. Also holds the UserPromptSubmit hook. It adds a style reminder to each message.
-
-The working-style projection uses `~/.claude/rules/asd-ste100-language.md` for
-user-facing word choice, sentence style, tone, punctuation, and prose form.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `session_env_cleanup.py` | SessionStart | Removes the current session's pre-existing `~/.claude/session-env/<session_id>/` directory and prunes sibling entries older than the stale-age threshold. Prevents `EEXIST` errors from non-recursive `mkdir` calls in the Bash tool on Windows. |
-| `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
-| `session_edit_tracker_cleanup.py` | SessionStart, SessionEnd | Deletes the tracker file for the running Claude Code conversation from the system temp directory — at start for a clean slate and at end for a clean exit. A tracker is read only by the conversation that wrote it, so a live idle tracker is kept while a peer cleans up |
-| `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
-| `untracked_repo_detector.py` | — | Retired legacy script; no longer registered |
-| `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
-| `orchestrator_auto_starter.py` | SessionStart | Opt-in (`CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED`) consumer of the shared SessionStart injector; emits orchestrator skill context when enabled. Manual `/orchestrator` unchanged. |
-| `issue_tracker_session_starter.py` | SessionStart | Opt-in (`CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED`) and repository-gated (git root in `~/.claude/project-paths.json`) issue-tracker skill context. |
-| `_path_setup.py` | — | Inserts the hooks directory on `sys.path` so SessionStart scripts import `hooks_constants` with top-level imports. |
-| `test_orchestrator_auto_starter.py` | — | Tests for `orchestrator_auto_starter.py` |
-| `test_issue_tracker_session_starter.py` | — | Tests for `issue_tracker_session_starter.py` |
-| `working_style_prompt.py` | SessionStart | Emits an `additionalContext` block with the fixed working-style prompt (running ledger, canonical language policy, outcome-first finish, scope discipline). Writes nothing and runs no tools itself. |
-| `style_reminder_prompt.py` | UserPromptSubmit | Adds the style reminder ("small words. few words. always. forever.") to every message, as `hookSpecificOutput.additionalContext`. Codex reads the same shape, so a manually wired Codex `hooks.json` can reuse this script too (see `docs/codex-compatibility.md`). Prints text and stops. |
-| `test_style_reminder_prompt.py` | — | Tests for `style_reminder_prompt.py` |
-| `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
-| `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
-| `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
-| `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
-| `test_task_list_loop_starter.py` | — | Tests for `task_list_loop_starter.py` |
-| `test__path_setup.py` | — | Tests for `_path_setup.py` |
-| `test_working_style_prompt.py` | — | Tests for `working_style_prompt.py` |
-
-## Conventions
-
-- `session_env_cleanup.py` is Windows-specific in effect but safe to run on all platforms; it exits 0 when the target directory does not exist.
-- Constants (stale-age threshold, directory names) live in `hooks_constants/session_env_cleanup_constants.py`.
-- Tests run with `python -m pytest session/test_<name>.py`.

package/hooks/validation/AGENTS.md

@@ -1,20 +1 @@
-# hooks/validation
 
-PostToolUse hooks that validate code quality after Claude writes or edits a file. Unlike the blocking hooks (which fire PreToolUse and can deny the write), these hooks run after the write and report errors that need a follow-up fix.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `mypy_validator.py` | PostToolUse (Write/Edit on `.py` files) | Runs mypy on the written file and blocks (via PostToolUse block decision) when type errors are found — catches missing attributes, wrong signatures, type mismatches, and import errors |
-| `hook_format_validator.py` | PostToolUse | Validates that a hook script's output JSON matches the expected Claude Code hook-output schema |
-| `test_mypy_validator.py` | — | Tests for `mypy_validator.py` |
-| `test_hook_format_validator.py` | — | Tests for `hook_format_validator.py` |
-
-## Conventions
-
-- `mypy_validator.py` resolves the project root via `CLAUDE_PROJECT_ROOT` or `git rev-parse --show-toplevel`.
-- It works on both WSL and Windows.
-- Constants (timeouts, max displayed errors) are inline in `mypy_validator.py`; longer tunables go in `hooks_constants/`.
-- The `eval_*.txt` files in this directory are evaluation exports used during development — not runtime artifacts.
-- Tests run with `python -m pytest validation/test_<name>.py`.

package/hooks/validators/AGENTS.md

@@ -1,52 +1 @@
-# hooks/validators
 
-A library of check modules used by the validation hooks. Each module focuses on one concern; `run_all_validators.py` runs them all and collects results. These modules do not hook into Claude Code directly — they are imported by the validation hooks.
-
-## Core infrastructure
-
-| File | Role |
-|---|---|
-| `validator_base.py` | Defines the `Violation` dataclass (`file`, `line`, `message`) used by every check module |
-| `validator_defaults.py` | Default configuration values shared across check modules |
-| `exempt_paths.py` | Path exemption logic — paths that checks skip (e.g. vendored code) |
-| `output_formatter.py` | Formats `Violation` lists into human-readable output |
-| `run_all_validators.py` | Entry point — runs every check module and aggregates results |
-| `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
-| `pyproject_config_discovery.py` | Shared walk-up primitive that resolves a tool's pyproject.toml config from an original target path, matching the `[tool.<name>]` table the tool owns |
-| `system_temporary_roots.py` | Shared membership for OS temp roots (`gettempdir` plus `TEMP` / `TMP` / `TMPDIR` / `RUNNER_TEMP`); mypy walk stop and PreToolUse staging both call it |
-| `python_style_helpers.py` | Shared source-line splitting and function-discovery helpers imported by `python_style_checks.py` |
-
-## Check modules
-
-| Module | What it checks |
-|---|---|
-| `abbreviation_checks.py` | Abbreviated names in Python code |
-| `code_quality_checks.py` | General code quality concerns (dead code, stub bodies, etc.) |
-| `comment_checks.py` | Inline comment presence and content |
-| `file_structure_checks.py` | File-level structural rules (line count, module layout) |
-| `git_checks.py` | Git-state checks (untracked files, merge conflicts) |
-| `magic_value_checks.py` | Magic numbers and strings |
-| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects; stops project-root walks at the system temp directory; detached gate files skip followed imports and time out as a skip (passed) |
-| `pr_reference_checks.py` | PR references in commit messages and changelogs |
-| `python_antipattern_checks.py` | Python-specific anti-patterns (bare `except`, `Any`, etc.) |
-| `python_style_checks.py` | Python style rules (naming, imports, type hints) |
-| `react_checks.py` | React/TSX-specific checks (class component patterns, PureComponent usage) |
-| `ruff_integration.py` | Runs ruff and converts its output to `Violation` objects |
-| `security_checks.py` | Security anti-patterns (hardcoded secrets, unsafe calls) |
-| `todo_checks.py` | TODO/FIXME markers without an associated issue reference |
-| `type_safety_checks.py` | Type-safety rules (no `Any`, no `cast`, no `# type: ignore`) |
-| `useless_test_checks.py` | Tests that check only existence or constant values |
-
-## Subdirectory
-
-| Directory | Role |
-|---|---|
-| `config/` | Constants module (`directory_exemption_constants.py`) holding the exemption directory-segment names that `validate_proposed_file` staging keeps |
-| `test_files/` | Fixture files used by the validator tests — not checked-in test code |
-
-## Conventions
-
-- Every check module exposes one or more functions that take file content or an AST and return a list of `Violation` objects.
-- Test files live beside the modules they test: `test_<module>.py`. Run with `python -m pytest validators/test_<name>.py`.
-- `conftest.py` provides shared test fixtures (sample files, fixture paths).
-- `README.md` in this directory documents the validator design and how to add a new check.

package/hooks/workflow/AGENTS.md

@@ -1,16 +1 @@
-# hooks/workflow
 
-PostToolUse hooks that run after Claude writes a file. They do not block the write; they run follow-up side effects — reformatting the written file and resetting the investigation tracker.
-
-## Key files
-
-| File | Event | What it does |
-|---|---|---|
-| `auto_formatter.py` | PostToolUse (Write/Edit) | Runs the project's auto-formatter (ruff, prettier, etc.) on the written file and sends a desktop notification when formatting changes are applied |
-| `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
-| `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
-
-## Conventions
-
-- `auto_formatter.py` exits 0 even on failure — it logs warnings to stderr but does not break Claude's flow.
-- Tests run with `python -m pytest workflow/test_<name>.py`.

package/output-styles/AGENTS.md

@@ -1,15 +1 @@
-# output-styles
 
-Output-style instruction files installed into `~/.claude/output-styles/` by `bin/install.mjs`. Each file instructs an agent or session to respond in a specific voice or format.
-
-## Files
-
-No output-style instruction files ship in this directory.
-
-## Format
-
-Each file uses YAML frontmatter (`name`, `description`, optional `keep-coding-instructions`) followed by Markdown instructions. The `keep-coding-instructions: true` flag tells Claude Code to keep the session's coding rules even when this style is active.
-
-## Adding a style
-
-Create a `.md` file with frontmatter and behavioral instructions, then run `bin/install.mjs` to copy it to `~/.claude/output-styles/`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.28.1",
+    "version": "2.29.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/AGENTS.md

@@ -1,56 +1 @@
----
-paths:
-  - "**/rules/**"
----
 
-# rules
-
-Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule without `paths:` frontmatter loads at the start of every session; a rule with `paths:` frontmatter loads only when the session works with a file its globs match. The `InstructionsLoaded` log records that match as a `path_glob_match` event. The `asd-ste100-language.md` file owns general user-facing language. Each other `.md` file covers one named behavior contract; hook-enforced rules are also backed by a Python hook in `hooks/`.
-
-## Files
-
-| File | Rule |
-|---|---|
-| `asd-ste100-language.md` | Sole general user-facing language authority; concise conversational adaptation of ASD-STE100 Issue 9 |
-| `agent-spawn-protocol.md` | Check context sufficiency before a spawn and ask subagents for file-and-line answers; `/prompt-generator` is recommended for a complex or user-facing spawn |
-| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
-| `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
-| `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
-| `claims-as-quotes.md` | On agent reports, hand-offs, review verdicts, and PR or commit prose, a design-gating claim travels with its quoted lines and `path:line` reference; chat keeps research-mode compact citations; a claim without its quote is a lead to check |
-| `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
-| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth, including §8 (TDD) and §7 (right-sizing); BDD is the outer process and TDD the inner loop |
-| `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
-| `destructive-commands.md` | Allowed removal forms and the ephemeral namespace the `destructive_command_blocker` auto-allows; keep destructive literals out of a Bash command string even as data |
-| `doc-inventory-integrity.md` | Three inventory shapes stay in step with the code: a per-directory `CLAUDE.md` file list, a package `README`/`SKILL.md` inventory, and an env-var summary table |
-| `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
-| `durable-post-artifacts.md` | GitHub post bodies never reference volatile scratch paths; text embeds inline and binary artifacts upload to the `artifacts` release with the permanent URL linked |
-| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
-| `failure-blast-radius.md` | Name what a raise stops — `RunFatal` for the whole run, `ItemBlocked` for one batch member — and keep the batch reaching a deliverable with parked members reported |
-| `falsify-before-green.md` | A check's green counts as evidence only after that same check ran red on a named break, with a passing control beside it |
-| `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
-| `filesystem-search.md` | Every filesystem search names a scope; `es.exe`, `Glob`, `Grep`, and `Read` are equally sanctioned, and the `unscoped_search_blocker` denies a walk from a root |
-| `gh-cli-conventions.md` | `--body-file` for every `gh` body; `--paginate --slurp` piped to external `jq` for every paginated list read |
-| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images; carries the review-response protocol |
-| `hedging-claims.md` | State the evidence or name the claim unverified; a hedge word stands in for evidence not gathered, prose discipline with no hook |
-| `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
-| `measurement-denominators.md` | Every reported count names what it scanned and carries its denominator; a rate needs two runs; the consumer cross-checks the count against the scope its denominator names |
-| `nas-ssh-invocation.md` | Reach the NAS through the paramiko-backed `nas_ssh_key.py` runner, which signs in-process; every ssh-family client reads the key through file permissions, refuses it, and stalls an unattended run on a password prompt |
-| `no-cross-skill-duplicate-helpers.md` | Within one skill a duplicated helper is blocked; across two skill folders a small self-contained copy is a sanctioned isolation tradeoff that draws a non-blocking advisory naming the source skill |
-| `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
-| `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
-| `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
-| `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
-| `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
-| `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
-| `shell-invocation.md` | Windows shell commands run through `pwsh`; no `$(...)`, backtick, or process substitution in a Bash tool command |
-| `testing.md` | Test quality and infrastructure standards |
-| `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
-| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking; recalled facts expire until re-checked this session |
-| `verify-runtime-state.md` | A "component is fine / not at fault" verdict rests on a live probe this session, never code reading or prior-session memory |
-| `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
-| `workers-done-before-complete.md` | A task reaches `completed` only when every spawned worker has finished and its results are merged into run state |
-| `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
-
-## Hook enforcement
-
-Rules marked with ⚡ in `~/.claude/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).