claude-dev-env 2.13.0 → 2.14.1

package/hooks/validators/test_health_check.py

@@ -1,35 +1,92 @@
 """Tests for validator health checks."""
 
-import tempfile
 from pathlib import Path
 
 import pytest
 
 from .health_check import (
+    SystemHealth,
     ValidatorHealth,
+    ValidatorStatus,
     check_validator_exists,
     check_all_validators,
     get_validator_version,
+    print_health_report,
 )
 
 
 class TestValidatorExists:
-    def test_existing_validator_healthy(self) -> None:
-        with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as temp_file:
-            temp_file.write(b"print('hello')")
-            temp_path = Path(temp_file.name)
-
-        try:
-            result = check_validator_exists(temp_path)
-            assert result.healthy is True
-            assert result.error is None
-        finally:
-            temp_path.unlink()
-
-    def test_missing_validator_unhealthy(self) -> None:
+    def test_existing_validator_is_ready(self, tmp_path: Path) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.write_text("print('hello')", encoding="utf-8")
+
+        result = check_validator_exists(validator_path)
+
+        assert result.is_healthy is True
+        assert result.healthy is result.is_healthy
+        assert result.status is ValidatorStatus.READY
+        assert result.error is None
+        assert result.is_present is True
+
+    def test_missing_validator_requires_a_file(self) -> None:
         result = check_validator_exists(Path("/nonexistent/validator.py"))
-        assert result.healthy is False
-        assert "not found" in result.error.lower()
+        assert result.is_healthy is False
+        assert result.status is ValidatorStatus.FILE_REQUIRED
+        assert result.is_present is False
+        assert "file required" in result.error.lower()
+
+    def test_unreadable_validator_reports_read_access_state(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.write_text("print('ready')", encoding="utf-8")
+
+        def raise_read_error(*_args: object, **_kwargs: object) -> str:
+            raise OSError("permission detail")
+
+        monkeypatch.setattr(Path, "read_text", raise_read_error)
+
+        result = check_validator_exists(validator_path)
+
+        assert result.is_healthy is False
+        assert result.status is ValidatorStatus.ACCESS_REQUIRED
+        assert result.is_present is True
+        assert "read access requires attention" in result.error.lower()
+
+    def test_directory_at_validator_path_requires_a_file(self, tmp_path: Path) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.mkdir()
+
+        result = check_validator_exists(validator_path)
+
+        assert result.is_healthy is False
+        assert result.status is ValidatorStatus.FILE_REQUIRED
+        assert result.is_present is False
+
+    def test_validator_disappearance_reports_file_required(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        validator_path = tmp_path / "validator.py"
+        validator_path.write_text("print('ready')", encoding="utf-8")
+
+        original_read_text = Path.read_text
+
+        def remove_before_read(
+            each_path: Path, **all_keyword_arguments: object
+        ) -> str:
+            each_path.unlink()
+            return original_read_text(each_path, **all_keyword_arguments)
+
+        monkeypatch.setattr(Path, "read_text", remove_before_read)
+
+        result = check_validator_exists(validator_path)
+
+        assert result.status is ValidatorStatus.FILE_REQUIRED
+        assert result.is_present is False
 
 
 class TestCheckAllValidators:
@@ -41,17 +98,45 @@ class TestCheckAllValidators:
 
 
 class TestGetValidatorVersion:
-    def test_version_changes_when_content_changes(self) -> None:
-        with tempfile.TemporaryDirectory() as temp_dir:
-            temp_path = Path(temp_dir)
-            validator_file = temp_path / "python_style_checks.py"
+    def test_version_changes_when_content_changes(self, tmp_path: Path) -> None:
+        validator_file = tmp_path / "python_style_checks.py"
+
+        validator_file.write_text("# version 1")
+        version1 = get_validator_version(tmp_path)
+
+        validator_file.write_text("# version 2 - different content")
+        version2 = get_validator_version(tmp_path)
+
+        assert version1 != version2
+        assert isinstance(version1, str)
+        assert len(version1) > 0
+
 
-            validator_file.write_text("# version 1")
-            version1 = get_validator_version(temp_path)
+def test_print_health_report_distinguishes_validator_states(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    health = SystemHealth(
+        all_healthy=False,
+        validators={
+            "missing_validator": ValidatorHealth(
+                name="missing_validator",
+                status=ValidatorStatus.FILE_REQUIRED,
+                error="Validator file required: missing_validator.py",
+            ),
+            "unreadable_validator": ValidatorHealth(
+                name="unreadable_validator",
+                status=ValidatorStatus.ACCESS_REQUIRED,
+                error="Validator read access requires attention: permission detail",
+            ),
+        },
+        python_version="3.12.0",
+        optional_tools={"mypy": True, "ruff": False},
+    )
 
-            validator_file.write_text("# version 2 - different content")
-            version2 = get_validator_version(temp_path)
+    print_health_report(health)
 
-            assert version1 != version2
-            assert isinstance(version1, str)
-            assert len(version1) > 0
+    report = capsys.readouterr().out
+    assert "[FILE REQUIRED] missing_validator" in report
+    assert "[ACCESS REQUIRED] unreadable_validator" in report
+    assert "[READY] mypy" in report
+    assert "[OPTIONAL] ruff" in report

package/hooks/workflow/AGENTS.md

@@ -0,0 +1,16 @@
+# 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/hooks/workflow/CLAUDE.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`.
+@AGENTS.md

package/installable-surfaces.manifest.json

@@ -14,6 +14,7 @@
     "audit-rubrics"
   ],
   "root_files": [
+    "AGENTS.md",
     "CLAUDE.md",
     "codex-capability-map.json",
     "installable-surfaces.manifest.json"

package/output-styles/AGENTS.md

@@ -0,0 +1,15 @@
+# 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/output-styles/CLAUDE.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. The active caveman behavior lives in `agents/caveman.md`.
-
-## 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/`.
+@AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.13.0",
+    "version": "2.14.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -26,6 +26,7 @@
         "installable-surfaces.manifest.json",
         "_shared/",
         "audit-rubrics/",
+        "AGENTS.md",
         "CLAUDE.md",
         "!**/__pycache__/**",
         "!**/*.py[cod]",

package/rules/AGENTS.md

@@ -0,0 +1,61 @@
+---
+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. 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` | 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 |
+| `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 |
+| `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 |
+| `doc-prose-cuts.md` | Four sentence shapes to cut from prose: exclusion claims, justification sentences, conversation references, and time references |
+| `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 |
+| `eli11-replies.md` | Every chat reply the user reads follows one shape: action first, detail last, few words; `plain-language.md` governs word choice, this rule governs reply length and shape |
+| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
+| `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 and a See-also block for its seven siblings |
+| `hedging-claims.md` | State the evidence or name the claim unverified; the `hedging_language_blocker` Stop hook sends a hedged response back for a re-check |
+| `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 |
+| `opus5-communication-contract.md` | Visible concision, one-sentence first progress, important-change-only updates, outcome-first finals, thinking-disabled tool narration (`opus5-communication-contract-v1`) |
+| `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
+| `parallel-tools.md` | Make all independent tool calls in a single response |
+| `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 |
+| `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 |
+| `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/`).

package/rules/CLAUDE.md

@@ -1,61 +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. 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` | 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 |
-| `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 |
-| `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 |
-| `doc-prose-cuts.md` | Four sentence shapes to cut from prose: exclusion claims, justification sentences, conversation references, and time references |
-| `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 |
-| `eli11-replies.md` | Every chat reply the user reads follows one shape: action first, detail last, few words; `plain-language.md` governs word choice, this rule governs reply length and shape |
-| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
-| `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 and a See-also block for its seven siblings |
-| `hedging-claims.md` | State the evidence or name the claim unverified; the `hedging_language_blocker` Stop hook sends a hedged response back for a re-check |
-| `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 |
-| `opus5-communication-contract.md` | Visible concision, one-sentence first progress, important-change-only updates, outcome-first finals, thinking-disabled tool narration (`opus5-communication-contract-v1`) |
-| `paired-test-coverage.md` | A public function omitted by a module's established paired test suite must get a behavioral test |
-| `parallel-tools.md` | Make all independent tool calls in a single response |
-| `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 |
-| `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 |
-| `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/`).
+@AGENTS.md

package/rules/code-standards.md

@@ -1,6 +1,6 @@
 # Code Standards
 
-> **Canonical policy:** repository-root [`AGENTS.md`](../../../AGENTS.md) — the human and AI review contract for code quality.
+> **Checked-in review contract:** [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md) — the human and AI review contract for code quality.
 > **Compact projection:** [`CODE_RULES.md`](../docs/CODE_RULES.md) — validated summary for generation load.
 > **Production enforcement:** `hooks/blocking/code_rules_enforcer.py` — hand-maintained Write/Edit gates; each mechanical rule carries a synchronization test.
 
@@ -8,12 +8,12 @@
 
 | Layer | Path | Role |
 |---|---|---|
-| Canonical | `AGENTS.md` (repo root) | Full review criteria for PR agents; BugBot sync source |
+| Contract | `.cursor/BUGBOT.md` | Full review criteria for PR agents |
 | Projection | `docs/CODE_RULES.md` | Compact always-load reference; must not diverge from AGENTS |
 | Enforcer | `hooks/blocking/code_rules_enforcer.py` | Hand-maintained blockers; not generated from the docs |
 | Session rules | `rules/*.md` | Runtime session policy (questions, tasks, shell) |
 
-Load `AGENTS.md` when reviewing a PR or resolving a policy conflict. Load `CODE_RULES.md` when generating code under the compact checklist. Prefer linking these refs over restating rules.
+Load `.cursor/BUGBOT.md` when reviewing a PR or resolving a policy conflict. Load `CODE_RULES.md` when generating code under the compact checklist. Prefer linking these refs over restating rules.
 
 Two standards live in the canonical policy in full (and in the projection by name):
 
@@ -30,10 +30,6 @@ BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers
 | Task tracking / worker completion | [`workers-done-before-complete.md`](workers-done-before-complete.md) |
 | Multi-step task list | skill `task-build` (see agents catalog) |
 
-## Synchronization
+## Validation
 
-Mechanical enforcer coverage is checked by `tests/test_agents_policy_parity.py` and the existing `hooks/blocking/test_code_rules_enforcer*.py` suite. BugBot projection drift is checked with:
-
-```
-python .github/scripts/sync_ai_rules.py --check
-```
+Mechanical enforcer coverage is checked by the existing `hooks/blocking/test_code_rules_enforcer*.py` suite.

package/rules/doc-prose-cuts.md

@@ -51,7 +51,7 @@ After writing, ask: read a year from now by someone who knew no earlier state, d
 ## Enforcement
 
 - **Write-time.** `state_description_blocker` (PreToolUse on Write|Edit) blocks historical and comparative phrases in `.md` prose, code comments, and Python docstrings. A phrase wrapped in double quotes or backticks inside a docstring counts as a mention and is skipped. The denial names the matched phrases and shows a rewrite.
-- **AI review.** The claude-dev-env repository's root `AGENTS.md`, the AI-review fan-out source, names the other three shapes as findings an agent applies to the `.md` lines a PR changes. No hook backs them: telling a justification sentence from a load-bearing one needs meaning a regex cannot read.
+- **AI review.** The claude-dev-env repository's `.cursor/BUGBOT.md` names the other three shapes as findings an agent applies to the `.md` lines a PR changes. Judgment-based review covers these shapes because a regex cannot read sentence meaning.
 
 ## Sibling rule
 

package/scripts/AGENTS.md

@@ -0,0 +1,62 @@
+# 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 |
+|---|---|
+| `claude_chain_runner.py` | Runs a `claude` invocation through a fallback chain (`~/.claude/claude-chain.json`) with `--routing-mode usage_ranked` (default: probe weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, highest remaining first) or `ordered_account` (config list order; non-usage failures stop as `advisor_blocked`); falls over only on a usage-limit failure; returns `terminal_status` / optional `session_id` on the outcome; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
+| `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try order |
+| `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
+| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv with no turn cap (the timeout is the only bound), mints a unique leader socket, captures streams, refuses a timeout that is missing, below `MIN_WORKER_TIMEOUT_SECONDS`, or above the `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) ceiling, kills the whole process tree on timeout with grace and retries the kill-and-drain round once, classifies ok/usage_limit/auth_failure/timeout/kill_failed/error; exports `require_timeout_within_bounds` so a dispatcher can apply the same bounds without launching; imported by `spawn_grok_batch.py` and `resolve_worker_spawn.py` |
+| `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
+| `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
+| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, optionally binds a unique worker advisor per role via the lead-supplied `advisor.launcher` (placeholder default in constants), injects `advisor_session_id`, requires the same session ENDORSE or bounded CORRECTION/PLAN then ENDORSE, classifies bind/verdict/timeout/missing-launcher failures as `advisor_blocked`, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
+| `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 |
+| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
+| `active_capability_references.py` | Inventories committed skill, agent, and command names and scans package markdown for active slash or backticked capability references; fails ban-listed names outside inert historical/example fences |
+| `verify_installable_package.py` | Verifies the published package: runs real `npm pack`, checks every surface in `installable-surfaces.manifest.json` appears in the tarball, requires each `hooks.json` `.py` command to be git-tracked, and smoke-compiles those scripts (`node --check` on `bin/install.mjs`) |
+
+## 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 |
+| `Sync-RepoMain.ps1` | Fast-forwards a main-tracking mirror (`-RepoPath`, required) to its remote main using `merge --ff-only`; refuses a different checkout or a diverged branch, logs each run to `-LogPath`, and exits non-zero so a scheduled-task history row surfaces the problem. `-StashDirty` stashes tracked changes right before the fast-forward under a dated `pre-sync stash` message and leaves the stash in the list |
+| `check.ps1` | Runs the full code-quality check suite |
+| `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
+| `Capture-PoolHealth.ps1` | Captures Windows memory pool counters, high-handle processes, and kernel pool tags (via `NtQuerySystemInformation` class 22), prints a threshold verdict with a remediation map, and exits non-zero when any alert threshold fires |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
+| `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
+| `profile-isolation-launchers/` | Profile-launcher contract plus MCP activation, Windows shortcut source semantics, and version preflight: profiles manifest, shared-path allowlist, profile resolver, `CLAUDE_CONFIG_DIR` authority, lean/full MCP bundle materialization into profile `mcp.json`, pure CLI/Desktop version-compatibility classifier consumed by launcher preflight, read-only shortcut inventory and preview reconcile under `windows/`. Live launcher execution, provenance pin, live shortcut mutation, and L1 deploy stay residual |
+| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
+| `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
+
+## Running tests
+
+Python scripts (pytest):
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```
+
+Profile-isolation launcher contract (node:test):
+
+```bash
+node --test packages/claude-dev-env/scripts/profile-isolation-launchers/**/*.test.mjs
+```
+
+PowerShell scripts (Pester 5+, `*.Tests.ps1`):
+
+```powershell
+Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
+```

package/scripts/CLAUDE.md

@@ -1,62 +1 @@
-# 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 |
-|---|---|
-| `claude_chain_runner.py` | Runs a `claude` invocation through a fallback chain (`~/.claude/claude-chain.json`) with `--routing-mode usage_ranked` (default: probe weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, highest remaining first) or `ordered_account` (config list order; non-usage failures stop as `advisor_blocked`); falls over only on a usage-limit failure; returns `terminal_status` / optional `session_id` on the outcome; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
-| `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try order |
-| `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
-| `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv with no turn cap (the timeout is the only bound), mints a unique leader socket, captures streams, refuses a timeout that is missing, below `MIN_WORKER_TIMEOUT_SECONDS`, or above the `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) ceiling, kills the whole process tree on timeout with grace and retries the kill-and-drain round once, classifies ok/usage_limit/auth_failure/timeout/kill_failed/error; exports `require_timeout_within_bounds` so a dispatcher can apply the same bounds without launching; imported by `spawn_grok_batch.py` and `resolve_worker_spawn.py` |
-| `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |
-| `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
-| `spawn_grok_batch.py` | Launches a fleet of headless grok workers from a JSON batch spec: gates once through the preflight, refuses a spec whose `timeout_seconds` exceeds `MAXIMUM_WORKER_TIMEOUT_SECONDS` (5400) rather than clamping it, assembles each prompt from part files, optionally binds a unique worker advisor per role via the lead-supplied `advisor.launcher` (placeholder default in constants), injects `advisor_session_id`, requires the same session ENDORSE or bounded CORRECTION/PLAN then ENDORSE, classifies bind/verdict/timeout/missing-launcher failures as `advisor_blocked`, staggers starts, runs each through `grok_headless_runner.py`, and emits one batch summary JSON |
-| `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 |
-| `resolve_worker_spawn.py` | Dispatches a worker role through grok then claude fallback tiers (preflight, headless grok, `claude_agent_required` handoff, optional claude headless); applies `require_timeout_within_bounds` before the preflight, so an out-of-bounds `--timeout-seconds` prints a `timeout_out_of_bounds` outcome and exits 3 on every tier; protocol: [`../_shared/pr-loop/worker-spawn.md`](../_shared/pr-loop/worker-spawn.md) |
-| `active_capability_references.py` | Inventories committed skill, agent, and command names and scans package markdown for active slash or backticked capability references; fails ban-listed names outside inert historical/example fences |
-| `verify_installable_package.py` | Verifies the published package: runs real `npm pack`, checks every surface in `installable-surfaces.manifest.json` appears in the tarball, requires each `hooks.json` `.py` command to be git-tracked, and smoke-compiles those scripts (`node --check` on `bin/install.mjs`) |
-
-## 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 |
-| `Sync-RepoMain.ps1` | Fast-forwards a main-tracking mirror (`-RepoPath`, required) to its remote main using `merge --ff-only`; refuses a different checkout or a diverged branch, logs each run to `-LogPath`, and exits non-zero so a scheduled-task history row surfaces the problem. `-StashDirty` stashes tracked changes right before the fast-forward under a dated `pre-sync stash` message and leaves the stash in the list |
-| `check.ps1` | Runs the full code-quality check suite |
-| `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
-| `Capture-PoolHealth.ps1` | Captures Windows memory pool counters, high-handle processes, and kernel pool tags (via `NtQuerySystemInformation` class 22), prints a threshold verdict with a remediation map, and exits non-zero when any alert threshold fires |
-
-## Subdirectories
-
-| Entry | Description |
-|---|---|
-| `ci/` | CI-only adapters; `windows-installer-lifecycle.ps1` runs the Node installer 16-check driver under isolated HOME/USERPROFILE/GIT_CONFIG_GLOBAL and writes bounded evidence |
-| `dev_env_scripts_constants/` | Named constants (`timing.py`, `grok_worker_constants.py`, …) for scripts in this directory, including worker-advisor placeholder launcher/model/effort, four verdict signals, correction cap, and advisor timeout |
-| `profile-isolation-launchers/` | Profile-launcher contract plus MCP activation, Windows shortcut source semantics, and version preflight: profiles manifest, shared-path allowlist, profile resolver, `CLAUDE_CONFIG_DIR` authority, lean/full MCP bundle materialization into profile `mcp.json`, pure CLI/Desktop version-compatibility classifier consumed by launcher preflight, read-only shortcut inventory and preview reconcile under `windows/`. Live launcher execution, provenance pin, live shortcut mutation, and L1 deploy stay residual |
-| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
-| `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
-
-## Running tests
-
-Python scripts (pytest):
-
-```bash
-python -m pytest packages/claude-dev-env/scripts/tests/
-```
-
-Profile-isolation launcher contract (node:test):
-
-```bash
-node --test packages/claude-dev-env/scripts/profile-isolation-launchers/**/*.test.mjs
-```
-
-PowerShell scripts (Pester 5+, `*.Tests.ps1`):
-
-```powershell
-Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
-```
+@AGENTS.md

package/scripts/codex_compat_materializer.py

@@ -26,6 +26,7 @@ manifest_indentation_width = 2
 publish_plan_max_positional_arguments = 3
 publish_plan_failure_injector_position = 2
 frontmatter_unsupported_fields = ("tools", "model", "color")
+instruction_alias_filenames = frozenset({"AGENTS.md", "CLAUDE.md"})
 full_prune_opt_in_flag = "--allow-prune-all"
 unreadable_source_root_message = (
     "source root is missing or is not a directory, so nothing was planned or changed; "
@@ -430,6 +431,9 @@ def discover_agents(config: MaterializerConfig) -> list[ClaudeAgent]:
         raise MaterializerError(f"{reparse_source_root_message}: {config.source_root}")
     all_agents: list[ClaudeAgent] = []
     for each_path in sorted(config.source_root.rglob("*.md"), key=lambda path: path.as_posix().casefold()):
+        if each_path.name in instruction_alias_filenames:
+            _validate_containment(config.source_root, each_path)
+            continue
         if _is_reparse_point(each_path):
             raise MaterializerError(f"source reparse point is not allowed: {each_path}")
         relative_source = each_path.relative_to(config.source_root).as_posix()

package/scripts/dev_env_scripts_constants/AGENTS.md

@@ -0,0 +1,21 @@
+# 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); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
+| `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
+| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, routing-mode tokens (`usage_ranked` / `ordered_account`), outcome `terminal_status` values (`served` / `advisor_blocked` / `chain_exhausted` / `timeout`), the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes (including advisor-blocked); `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
+| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
+| `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, `spawn_grok_batch.py`, and `resolve_worker_spawn.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, worker timeouts (default, plus the floor and the `MAXIMUM_WORKER_TIMEOUT_SECONDS` ceiling that the batch spec parse, the headless runner, and the spawn dispatcher all enforce, each bound carrying one rejection template shared by those sites, plus launch-failure return code and post-kill grace), the process-tree kill attempt limit and kill-failed classification, the preflight ping's single-turn cap, ping-cache keys and TTL, batch-spec and summary JSON keys, worker-advisor placeholder launcher/model/effort tokens, four verdict signals, MAXIMUM_WORKER_ADVISOR_CORRECTIONS, advisor_blocked classification, and advisor_session_id report keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
+| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review ultra --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers; finding severity tokens (`blocker` / `high` / `medium` / `low` / `nit`), verification verdict tokens, loop terminal tokens (`clean` / `nits_fixed` / `advisor_blocked`), and pure helpers for retained-finding checks, head recording, terminal resolution, and terminal encoding |
+| `active_capability_constants.py` | `active_capability_references.py` - package skills/agents/commands directory names, skill manifest filename, ban-listed capability names, inert fence languages, slash and backtick extract patterns, fence open/close patterns, banned-reason prefix, UTF-8 encoding, and newline join separator |
+| `verify_installable_package_constants.py` | `verify_installable_package.py` - manifest filename and keys, npm pack / tarball / plugin-root tokens, git and node smoke argv pieces, surface classification labels, exit codes, and CLI status headers |
+| `__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. `code_review_constants.py` also exports pure helpers that resolve review-loop terminals from those tokens.