claude-dev-env 1.68.0 → 1.69.1

package/hooks/blocking/test_code_rules_enforcer_file_global_constants.py

@@ -32,6 +32,7 @@ TYPESCRIPT_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example.ts"
 TOP_LEVEL_CONFIG_FILE_PATH = "config/timing.py"
 NESTED_CONFIG_FILE_PATH = "packages/claude-dev-env/hooks/config/example_constants.py"
 BACKSLASH_CONFIG_FILE_PATH = "packages\\claude-dev-env\\hooks\\config\\example_constants.py"
+WORKFLOW_REGISTRY_FILE_PATH = "packages/claude-dev-env/hooks/blocking/workflow/app_info/states.py"
 
 
 def test_should_flag_constant_used_by_only_one_function() -> None:
@@ -114,6 +115,14 @@ def test_should_exempt_test_files() -> None:
     assert issues == [], f"Expected test file exemption, got: {issues}"
 
 
+def test_should_exempt_workflow_registry_files() -> None:
+    source = "UPPER = 1\n\ndef lonely_caller():\n    return UPPER\n"
+    issues = code_rules_enforcer.check_file_global_constants_use_count(
+        source, WORKFLOW_REGISTRY_FILE_PATH
+    )
+    assert issues == [], f"Expected workflow-registry file exemption, got: {issues}"
+
+
 def test_should_flag_constant_used_only_in_decorator_of_one_function() -> None:
     source = (
         "TIMEOUT = 5.0\n"

package/hooks/diagnostic/CLAUDE.md

@@ -0,0 +1,43 @@
+# hooks/diagnostic
+
+Hooks and scripts that collect, store, and query hook-firing records. The pipeline reads session JSONL transcripts, extracts hook attachment records, and writes them as rows into a Neon (Postgres) `hook_events` table.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `migrations/` | SQL migration files for the `hook_events` schema |
+| `queries/` | Parameterized SQL queries for inspecting blocked commands |
+
+## Key files
+
+| File | What it does |
+|---|---|
+| `hook_log_init.py` | One-time setup: creates the Neon schema (runs `schema.sql`), then verifies read-write parity with a sentinel round-trip |
+| `hook_log_extractor.py` | Stop hook — reads per-session JSONL transcripts and ingests new `hook_*` attachment records into the `hook_events` table; idempotent via a UNIQUE constraint on `(source_jsonl_path, source_line_number)` |
+| `hook_log_stop_wrapper.py` | Thin wrapper that invokes `hook_log_extractor.py` from the Stop lifecycle event |
+| `schema.sql` | DDL for the `hook_events` table, `blocked_commands` view, and supporting indexes |
+| `requirements-hook-logs.txt` | Runtime dependencies (`psycopg`) for the extractor |
+| `requirements-hook-logs-dev.txt` | Dev/test dependencies |
+| `test_hook_log_extractor.py` | Tests for the extractor |
+| `test_hook_log_init.py` | Tests for the schema-init script |
+| `test_hook_log_stop_wrapper.py` | Tests for the Stop wrapper |
+
+## Schema overview (`schema.sql`)
+
+The `hook_events` table captures one row per hook firing:
+
+- `hook_event`, `hook_name`, `hook_category` — what fired
+- `outcome` — `allowed`, `blocked`, or `ask`
+- `tool_name`, `command_excerpt` — what tool was called
+- `session_id`, `git_branch`, `cwd` — context
+- `duration_ms`, `exit_code` — timing and result
+- `source_jsonl_path`, `source_line_number` — idempotency key
+
+The `blocked_commands` view filters to `outcome = 'blocked'`.
+
+## Conventions
+
+- The extractor exits 0 even when Neon is unreachable (offline-graceful); it logs to `OFFLINE_WARNING_LOG` and does not block session end.
+- Constants for the extractor (table name, offset state file, timeout) live in `hooks_constants/hook_log_extractor_constants.py`.
+- Tests run with `python -m pytest diagnostic/test_hook_log_*.py`.

package/hooks/diagnostic/migrations/CLAUDE.md

@@ -0,0 +1,16 @@
+# hooks/diagnostic/migrations
+
+SQL migration files for the `hook_events` Neon schema. Each file applies a schema change to the `hook_events` table or its indexes.
+
+## Files
+
+| File | What it does |
+|---|---|
+| `2026-04-25-drop-themes-hook-events.sql` | Drops the `themes` hook-events table variant |
+| `README.md` | Notes on the migration approach |
+
+## Conventions
+
+- Run migrations manually against the Neon database using `psql` or the Neon console.
+- The baseline schema lives in `diagnostic/schema.sql`.
+- File names follow `YYYY-MM-DD-<description>.sql` for chronological ordering.

package/hooks/diagnostic/queries/CLAUDE.md

@@ -0,0 +1,19 @@
+# hooks/diagnostic/queries
+
+Parameterized SQL queries for inspecting the `hook_events` Neon table. Run these directly against the Neon database to analyze hook-firing patterns.
+
+## Files
+
+| File | What it returns |
+|---|---|
+| `block_details_for_hook.sql` | Full details for all blocked events matching a given hook name |
+| `blocks_by_category.sql` | Count of blocks grouped by hook category |
+| `blocks_by_tool.sql` | Count of blocks grouped by tool name |
+| `blocks_last_7_days.sql` | All blocked events from the last 7 days |
+| `top_blockers_last_24_hours.sql` | Hook names with the most blocks in the last 24 hours |
+| `top_blockers_overall.sql` | Hook names with the most blocks across all time |
+
+## Conventions
+
+- Queries target the `hook_events` table and `blocked_commands` view defined in `diagnostic/schema.sql`.
+- Run with `psql $DATABASE_URL -f <query>.sql` or paste into the Neon console.

package/hooks/git-hooks/CLAUDE.md

@@ -0,0 +1,28 @@
+# 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 the CODE_RULES gate (`precommit_code_rules_gate.py`) over staged changes; exits 1 when any staged file has a blocking violation |
+| `pre_push.py` | `pre-push` | Runs the verified-commit gate check before a push reaches the remote |
+| `post_commit.py` | `post-commit` | Runs after a commit lands; performs any post-commit bookkeeping |
+| `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` |
+
+## 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/CLAUDE.md

@@ -0,0 +1,21 @@
+# 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/CLAUDE.md

@@ -0,0 +1,60 @@
+# 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 |
+| `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
+| `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 |
+| `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
+| `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
+| `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |
+| `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
+| `dead_config_field_constants.py` | Patterns for detecting unused dataclass config fields |
+| `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
+| `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
+| `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
+| `doc_gist_auto_publish_constants.py` | Sentinel marker and URL patterns for the doc-gist auto-publish hook |
+| `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
+| `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
+| `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 |
+| `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
+| `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
+| `html_companion_constants.py` | Blocked URL schemes and other config for the `.md`-to-`.html` companion hook |
+| `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
+| `md_to_html_blocker_constants.py` | Path exemptions and trigger patterns for the markdown-to-html blocker |
+| `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
+| `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 |
+| `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
+| `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
+| `pr_converge_bugteam_enforcer_constants.py` | State keys and timing config for the bugteam-parallel enforcer |
+| `pr_converge_bugteam_enforcer_state.py` | State-file helpers for the bugteam enforcer |
+| `pr_description_enforcer_constants.py` | PR-description shape rules and command patterns |
+| `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
+| `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
+| `project_paths_reader.py` | Loads `~/.claude/project-paths.json` — the per-user project-path registry |
+| `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
+| `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 |
+| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects |
+| `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 |
+| `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
+| `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 |
+
+## Conventions
+
+- Every file in this package is a pure constants module — 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` and `pre_tool_use_stdin.py` are utility modules (not pure constants) but live here because they are shared across many hooks.

package/hooks/hooks_constants/blocking_check_limits.py

@@ -17,6 +17,8 @@ MAX_BOUNDARY_TYPE_ISSUES: int = 5
 ALL_BANNED_PREFIX_NAMES: tuple[str, ...] = ("handle_", "process_", "manage_", "do_")
 MAX_DOCSTRING_FORMAT_ISSUES: int = 5
 MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES: int = 5
+MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES: int = 5
+MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH: int = 2
 MAX_IGNORED_MUST_CHECK_RETURN_ISSUES: int = 5
 MAX_TYPE_ESCAPE_HATCH_ISSUES: int = 5
 MAX_THIN_WRAPPER_ISSUES: int = 1

package/hooks/lifecycle/CLAUDE.md

@@ -0,0 +1,18 @@
+# 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 |
+| `pr_converge_bugteam_skill_tracker.py` | PostToolUse | Tracks which bugteam skill runs have completed within a pr-converge loop, so the enforcer can verify parallel execution |
+| `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_pr_converge_bugteam_skill_tracker.py` | — | Tests for `pr_converge_bugteam_skill_tracker.py` |
+
+## Conventions
+
+- Constants for these hooks (stale-age threshold, cache directory, known-hook-count file) live in `hooks_constants/session_env_cleanup_constants.py` and `hooks_constants/pr_converge_bugteam_enforcer_constants.py`.
+- Tests run with `python -m pytest lifecycle/test_<name>.py`.

package/hooks/observability/CLAUDE.md

@@ -0,0 +1,16 @@
+# 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 |
+| `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
+
+## 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/CLAUDE.md

@@ -0,0 +1,21 @@
+# hooks/session
+
+SessionStart and SessionEnd hooks that manage per-session resources: cleaning up stale directories at startup and pruning plugin data at shutdown.
+
+## 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 |
+| `plugin_data_dir_cleanup.py` | SessionEnd | Prunes stale plugin data directories |
+| `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
+| `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
+| `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
+| `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.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/CLAUDE.md

@@ -0,0 +1,19 @@
+# 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` |
+
+## 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/CLAUDE.md

@@ -0,0 +1,49 @@
+# 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 |
+
+## 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 |
+| `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 |
+| `verify_paths.py` | Validates that file paths referenced in code actually exist |
+
+## Subdirectory
+
+| Directory | Role |
+|---|---|
+| `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/CLAUDE.md

@@ -0,0 +1,22 @@
+# hooks/workflow
+
+PostToolUse hooks that trigger side-effects after Claude writes a file. They do not block writes; they produce companion artifacts or publish content automatically.
+
+## 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 |
+| `doc_gist_auto_publish.py` | PostToolUse (Write on `.html` files) | When an `.html` file has the `<!-- @publish-as-gist -->` marker, uploads it as a secret GitHub Gist and prints the htmlpreview URL into the harness output |
+| `md_to_html_companion.py` | PostToolUse (Write/Edit on `.md` files) | Generates a styled `.html` companion file from the `.md` source with dark-mode styling |
+| `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
+| `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
+| `test_doc_gist_auto_publish.py` | — | Tests for `doc_gist_auto_publish.py` |
+| `test_md_to_html_companion.py` | — | Tests for `md_to_html_companion.py` |
+
+## Conventions
+
+- All three main hooks exit 0 even on failure — they log warnings to stderr but do not break Claude's flow.
+- `doc_gist_auto_publish.py` checks for the `<!-- @publish-as-gist -->` marker before doing any work; HTML files without it are ignored.
+- Constants (marker text, blocked URL schemes, gist upload script path) live in `hooks_constants/doc_gist_auto_publish_constants.py` and `hooks_constants/html_companion_constants.py`.
+- Tests run with `python -m pytest workflow/test_<name>.py`.

package/package.json

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

package/rules/CLAUDE.md

@@ -0,0 +1,46 @@
+# rules
+
+Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code loads these as always-on behavioral constraints for every session. Each `.md` file covers one named rule; hook-enforced rules are also backed by a Python hook in `hooks/`.
+
+## Files
+
+| File | Rule |
+|---|---|
+| `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
+| `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 |
+| `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
+| `code-reviews.md` | Mandatory protocol for responding to GitHub PR review feedback |
+| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth |
+| `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
+| `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
+| `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
+| `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
+| `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
+| `gh-body-file.md` | Use `--body-file` with a temp file for all `gh` commands carrying markdown body content |
+| `gh-paginate.md` | Use `--paginate --slurp` piped to external `jq` for paginated GitHub API list endpoints |
+| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images |
+| `hook-prose-matches-detector.md` | Hook prose descriptions match what the hook actually detects |
+| `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
+| `no-cross-skill-duplicate-helpers.md` | No duplicating shared helpers across skills; use `_shared/` |
+| `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
+| `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
+| `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `parallel-tools.md` | Make all independent tool calls in a single response |
+| `plain-language.md` | Everyday words, short active sentences, lead with the answer |
+| `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
+| `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
+| `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |
+| `shell-invocation-policy.md` | All Windows shell commands use `pwsh`; `powershell.exe`, `cmd /c`, and `bash -c` are blocked |
+| `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
+| `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 the user |
+| `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
+| `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
+
+## Hook enforcement
+
+Rules marked with ⚡ in `packages/claude-dev-env/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/`).

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

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. A second gate validator, `check_docstring_fallback_branch_coverage`, covers one deterministic slice of the free-form prose: a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature and no single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the two gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Two more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the three gated slices.
 
 ## What to check before you write the docstring
 

package/scripts/CLAUDE.md

@@ -0,0 +1,34 @@
+# scripts
+
+Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each script is a standalone tool a user or hook can invoke directly.
+
+## Scripts
+
+| File | Purpose |
+|---|---|
+| `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
+| `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
+| `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
+
+## PowerShell scripts
+
+| File | Purpose |
+|---|---|
+| `Audit-ShellPolicy.ps1` | Audits Bash tool calls in session transcripts against the `pwsh`-only shell policy |
+| `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
+| `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
+| `check.ps1` | Runs the full code-quality check suite |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `dev_env_scripts_constants/` | Named constants (`timing.py`) for scripts in this directory |
+| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
+| `tests/` | pytest suite for the Python scripts in this directory |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -0,0 +1,14 @@
+# dev_env_scripts_constants
+
+Named constants for scripts in `scripts/`. Follows the project convention that timeouts, delays, and retries live in `timing.py`.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `timing.py` | `sweep_empty_dirs.py` — `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode) |
+| `__init__.py` | Empty package marker |
+
+## Convention
+
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.

package/scripts/sync_to_cursor/CLAUDE.md

@@ -0,0 +1,23 @@
+# sync_to_cursor
+
+Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
+| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
+| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
+| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
+| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
+| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
+| `__init__.py` | Empty package marker |
+
+## Layout resolution
+
+`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
+
+## Tests
+
+Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.

package/scripts/tests/CLAUDE.md

@@ -0,0 +1,18 @@
+# scripts/tests
+
+pytest suite for the Python scripts in `scripts/`.
+
+## Test files
+
+| File | Covers |
+|---|---|
+| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
+| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
+| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
+| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
+
+## Running
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```

package/skills/CLAUDE.md

@@ -0,0 +1,66 @@
+# Skills Directory
+
+Each skill is a self-contained folder Claude Code loads on demand. At startup, only the skill's `name` and `description` metadata load. The full `SKILL.md` body and any support files load only when a skill becomes relevant to the conversation.
+
+## Skill folder convention
+
+| Item | Role |
+|---|---|
+| `SKILL.md` | Required entry point. YAML frontmatter with `name` and `description` (the trigger). Body holds the skill's full instructions. |
+| `scripts/` | Python helper scripts the skill invokes at runtime. |
+| `workflow/` | `.mjs` workflow scripts run via the `Workflow` tool. |
+| `templates/` | Template files the skill or workflow renders at build time. |
+| `reference/` | Reference docs the skill cites or the workflow reads. |
+| `*_constants/` | Python package of named constants imported by `scripts/`. |
+
+Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/bin/install.mjs`. See `docs/references/skill-install-system.md` for the install pipeline.
+
+## Shared support code
+
+`_shared/` — support code used by more than one skill. It holds `pr-loop/`, which provides prompt templates and Python helper scripts shared between `bugteam` and `pr-converge`.
+
+## Skill groups
+
+**Planning and implementation**
+- `anthropic-plan` — creates a source-grounded plan packet before any code changes
+- `implement` — structured implementation from an existing plan packet
+- `bdd-protocol` — BDD depth: Example Mapping, scenario quality, outside-in layout
+- `verified-build` — build + test loop that gates on a verifier verdict
+
+**PR review and convergence**
+- `autoconverge` — autonomous single-run workflow that drives a PR to ready
+- `pr-converge` — paced convergence loop across `ScheduleWakeup` ticks
+- `bugteam` — open-loop audit-fix until convergence
+- `pr-review-responder` — fetches all reviewer comments and replies systematically
+- `pr-consistency-audit` — cross-file consistency check on a PR diff
+- `copilot-review` — requests and polls a GitHub Copilot review
+- `findbugs` / `fixbugs` — find bugs then fix them in separate passes
+- `code` — strict-mode code generation session
+
+**Research and discovery**
+- `deep-research` — multi-source research with citation
+- `research-mode` — activates anti-hallucination discipline for a session
+- `recall` — retrieves facts from memory files
+- `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
+- `everything-search` — file-system search via the Everything MCP tool
+- `caveman` — trims noise from a draft artifact
+
+**Session and workflow management**
+- `session-log` — logs a session report to the Obsidian vault
+- `session-tidy` — tidies the session folder
+- `bg-agent` — launches a background agent
+- `task-build` — gathers open tasks
+- `update` — updates the dev-env package
+- `gh-paginate` — safe `gh api` pagination patterns
+- `fresh-branch` — creates a clean branch off main
+- `rebase` — rebases onto main
+- `gotcha` — records a hard-won lesson to memory
+- `logifix` — restores the Logitech Gaming Software (LCore) tray icon when it disappears on Windows
+- `refine` — refinement pass on an artifact
+- `structure-prompt` — structures a freeform prompt
+- `monitor-open-prs` — polls open PRs for status
+- `pre-compact` — compact-safe session handoff
+- `qbug` — required baseline PR audit; one clean-coder subagent loops audit → fix → commit → push until clean or stuck
+- `skill-builder` — complete skill-building lifecycle
+- `doc-gist` — uploads an HTML file as a secret gist
+- `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings

package/skills/_shared/CLAUDE.md

@@ -0,0 +1,11 @@
+# _shared
+
+Support code shared across multiple skills. Each subdirectory targets a specific cross-skill concern.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `pr-loop/` | Prompt templates and Python helper scripts used by both `bugteam` and `pr-converge` for their audit-fix loop. |
+
+Files here are not skills themselves and have no `SKILL.md`. They install alongside each consuming skill via the install pipeline in `packages/claude-dev-env/bin/install.mjs`.