claude-dev-env 2.12.0 → 2.14.0

package/bin/install.settings-defaults.test.mjs

@@ -26,12 +26,15 @@ const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PACKAGE_SETTINGS_PATH = join(PACKAGE_ROOT, 'settings.json');
 const INSTALL_ENTRY = join(PACKAGE_ROOT, 'bin', 'install.mjs');
 
-const EXPECTED_DENY_ENTRIES = [
+const EXPECTED_DENY_ENTRIES = [];
+const SAMPLE_MANAGED_DENY_ENTRIES = ['Edit($HOME/.claude/managed-test/**)'];
+const LEGACY_MANAGED_DENY_ENTRIES = [
     'Edit($HOME/.claude/verification/**)',
     'Write($HOME/.claude/code-review-stamps/**)',
     'Edit($HOME/.claude/code-review-stamps/**)',
     'MultiEdit($HOME/.claude/code-review-stamps/**)',
 ];
+const USER_OWNED_DENY_ENTRY = 'Bash(rm -rf /)';
 
 function packageDenyEntries() {
     const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
@@ -53,19 +56,18 @@ function runInstallerInSandbox(sandboxHome, installerArguments = []) {
     });
 }
 
-test('package settings.json publishes exactly the four managed deny entries', () => {
+test('package settings.json publishes no managed deny entries', () => {
     const denyEntries = packageDenyEntries();
-    assert.equal(denyEntries.length, 4);
     assert.deepEqual(denyEntries, EXPECTED_DENY_ENTRIES);
 });
 
 test('an array-valued permissions field is replaced so managed denies survive a round trip', () => {
     const targetSettings = { permissions: [] };
-    const result = mergeManagedPermissionsIntoSettings(targetSettings, EXPECTED_DENY_ENTRIES);
-    assert.equal(result.addedCount, EXPECTED_DENY_ENTRIES.length);
+    const result = mergeManagedPermissionsIntoSettings(targetSettings, SAMPLE_MANAGED_DENY_ENTRIES);
+    assert.equal(result.addedCount, SAMPLE_MANAGED_DENY_ENTRIES.length);
     assert.equal(Array.isArray(targetSettings.permissions), false);
     const roundTripped = JSON.parse(JSON.stringify(targetSettings));
-    assert.deepEqual(roundTripped.permissions.deny, EXPECTED_DENY_ENTRIES);
+    assert.deepEqual(roundTripped.permissions.deny, SAMPLE_MANAGED_DENY_ENTRIES);
 });
 
 test('npm pack includes package settings.json in the published artifact', () => {
@@ -88,25 +90,28 @@ test('npm pack includes package settings.json in the published artifact', () =>
     );
 });
 
-test('mergeManagedPermissionsIntoSettings adds each package deny exactly once', () => {
+test('mergeManagedPermissionsIntoSettings adds each managed deny exactly once', () => {
     const target = {
         permissions: {
             allow: ['Bash(git status)'],
             deny: ['Bash(rm -rf /)'],
         },
     };
-    const first = mergeManagedPermissionsIntoSettings(target, EXPECTED_DENY_ENTRIES);
-    assert.equal(first.addedCount, 4);
+    const first = mergeManagedPermissionsIntoSettings(target, SAMPLE_MANAGED_DENY_ENTRIES);
+    assert.equal(first.addedCount, SAMPLE_MANAGED_DENY_ENTRIES.length);
     assert.equal(first.alreadyPresentCount, 0);
-    assert.equal(target.permissions.deny.filter((each) => EXPECTED_DENY_ENTRIES.includes(each)).length, 4);
+    const managedDenyCount = target.permissions.deny.filter((each) => (
+        SAMPLE_MANAGED_DENY_ENTRIES.includes(each)
+    )).length;
+    assert.equal(managedDenyCount, SAMPLE_MANAGED_DENY_ENTRIES.length);
     assert.ok(target.permissions.deny.includes('Bash(rm -rf /)'));
     assert.deepEqual(target.permissions.allow, ['Bash(git status)']);
 
-    const second = mergeManagedPermissionsIntoSettings(target, EXPECTED_DENY_ENTRIES);
+    const second = mergeManagedPermissionsIntoSettings(target, SAMPLE_MANAGED_DENY_ENTRIES);
     assert.equal(second.addedCount, 0);
-    assert.equal(second.alreadyPresentCount, 4);
+    assert.equal(second.alreadyPresentCount, SAMPLE_MANAGED_DENY_ENTRIES.length);
     assert.equal(
-        target.permissions.deny.filter((each) => each === EXPECTED_DENY_ENTRIES[0]).length,
+        target.permissions.deny.filter((each) => each === SAMPLE_MANAGED_DENY_ENTRIES[0]).length,
         1,
     );
 });
@@ -118,18 +123,18 @@ test('pruneManagedPermissionsFromSettings removes only package-owned deny entrie
             ask: ['Edit(./**)'],
             deny: [
                 'Bash(rm -rf /)',
-                ...EXPECTED_DENY_ENTRIES,
+                ...SAMPLE_MANAGED_DENY_ENTRIES,
             ],
         },
     };
-    const outcome = pruneManagedPermissionsFromSettings(target, EXPECTED_DENY_ENTRIES);
-    assert.equal(outcome.removedCount, 4);
+    const outcome = pruneManagedPermissionsFromSettings(target, SAMPLE_MANAGED_DENY_ENTRIES);
+    assert.equal(outcome.removedCount, SAMPLE_MANAGED_DENY_ENTRIES.length);
     assert.deepEqual(target.permissions.deny, ['Bash(rm -rf /)']);
     assert.deepEqual(target.permissions.allow, ['Bash(git status)']);
     assert.deepEqual(target.permissions.ask, ['Edit(./**)']);
 });
 
-test('sandbox install adds all four deny entries once and is idempotent on repeat', () => {
+test('sandbox install keeps default managed denies empty on repeat', () => {
     const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
     try {
         const firstInstall = runInstallerInSandbox(sandboxHome, []);
@@ -139,30 +144,52 @@ test('sandbox install adds all four deny entries once and is idempotent on repea
         assert.ok(existsSync(settingsPath), 'settings.json written');
         const firstSettings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         const firstDeny = firstSettings.permissions?.deny ?? [];
-        for (const eachEntry of EXPECTED_DENY_ENTRIES) {
-            assert.ok(firstDeny.includes(eachEntry), `missing deny: ${eachEntry}`);
-            assert.equal(
-                firstDeny.filter((candidate) => candidate === eachEntry).length,
-                1,
-                `deny not unique: ${eachEntry}`,
-            );
-        }
+        assert.deepEqual(firstDeny, EXPECTED_DENY_ENTRIES);
 
         const manifestPath = join(sandboxHome, '.claude', '.claude-dev-env-manifest.json');
         const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-        assert.deepEqual(manifest.managedPermissions?.deny, EXPECTED_DENY_ENTRIES);
+        assert.deepEqual(manifest.managedPermissions?.deny ?? [], EXPECTED_DENY_ENTRIES);
 
         const secondInstall = runInstallerInSandbox(sandboxHome, []);
         assert.equal(secondInstall.status, 0, secondInstall.stderr || secondInstall.stdout);
         const secondSettings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         const secondDeny = secondSettings.permissions?.deny ?? [];
-        for (const eachEntry of EXPECTED_DENY_ENTRIES) {
-            assert.equal(
-                secondDeny.filter((candidate) => candidate === eachEntry).length,
-                1,
-                `repeat install duplicated deny: ${eachEntry}`,
-            );
-        }
+        assert.deepEqual(secondDeny, EXPECTED_DENY_ENTRIES);
+    } finally {
+        rmSync(sandboxHome, { recursive: true, force: true });
+    }
+});
+
+test('a normal upgrade retires manifest-owned denies and preserves user entries', () => {
+    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-upgrade-'));
+    try {
+        const initialInstall = runInstallerInSandbox(sandboxHome, []);
+        assert.equal(initialInstall.status, 0, initialInstall.stderr || initialInstall.stdout);
+
+        const settingsPath = join(sandboxHome, '.claude', 'settings.json');
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        settings.permissions = {
+            allow: ['Bash(git status)'],
+            ask: ['Edit(./**)'],
+            deny: [USER_OWNED_DENY_ENTRY, ...LEGACY_MANAGED_DENY_ENTRIES],
+        };
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
+
+        const manifestPath = join(sandboxHome, '.claude', '.claude-dev-env-manifest.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        manifest.managedPermissions = { deny: LEGACY_MANAGED_DENY_ENTRIES };
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+
+        const upgradedInstall = runInstallerInSandbox(sandboxHome, []);
+        assert.equal(upgradedInstall.status, 0, upgradedInstall.stderr || upgradedInstall.stdout);
+
+        const upgradedSettings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        assert.deepEqual(upgradedSettings.permissions?.deny, [USER_OWNED_DENY_ENTRY]);
+        assert.deepEqual(upgradedSettings.permissions?.allow, ['Bash(git status)']);
+        assert.deepEqual(upgradedSettings.permissions?.ask, ['Edit(./**)']);
+
+        const upgradedManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(Object.hasOwn(upgradedManifest, 'managedPermissions'), false);
     } finally {
         rmSync(sandboxHome, { recursive: true, force: true });
     }

package/bin/install.test.mjs

@@ -42,6 +42,7 @@ import {
     pruneRetiredHookEntriesFromSettings,
     retainNewestRunBackupOnly,
 } from './install.mjs';
+import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
     expandHomeDirectoryTokens,
     expandHomeDirectoryTokensInSettings,
@@ -204,6 +205,14 @@ test('CORE_SKILLS ships issue-tracker so the core group installs the skill the S
 });
 
 
+test('EVER_SHIPPED_SKILL_NAMES retains imagegen so reinstall prunes the retired skill', () => {
+    assert.ok(
+        EVER_SHIPPED_SKILL_NAMES.has('imagegen'),
+        'imagegen must remain in the retirement registry after the package stops shipping it',
+    );
+});
+
+
 test('CONTENT_DIRECTORIES includes audit-rubrics so installer copies category rubrics and prompts to ~/.claude/audit-rubrics/', () => {
     assert.ok(
         CONTENT_DIRECTORIES.includes('audit-rubrics'),
@@ -953,7 +962,6 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/state_description_blocker.py', timeout: 10 },
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/subprocess_budget_completeness.py', timeout: 10 },
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/hook_prose_detector_consistency.py', timeout: 10 },
-                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/verified_commit_message_accuracy_blocker.py', timeout: 10 },
                 ],
             },
             {
@@ -971,8 +979,8 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('FOLDED_HOOK_RELATIVE_PATHS contains all 16 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
-    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 17);
+test('FOLDED_HOOK_RELATIVE_PATHS contains all 15 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 16);
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/plain_language_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
@@ -992,7 +1000,6 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
         'blocking/state_description_blocker.py',
         'blocking/subprocess_budget_completeness.py',
         'blocking/hook_prose_detector_consistency.py',
-        'blocking/verified_commit_message_accuracy_blocker.py',
         'blocking/workflow_substitution_slot_blocker.py',
         'blocking/claude_md_orphan_file_blocker.py',
         'blocking/env_var_table_code_drift_blocker.py',
@@ -1660,6 +1667,31 @@ test('collectFiles skips every named cache directory and loose bytecode file', (
 });
 
 
+test('copyTree copies AGENTS.md with agent definitions', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-copy-agents-source-'));
+    const destinationRoot = mkdtempSync(join(tmpdir(), 'cdev-copy-agents-destination-'));
+    try {
+        writeFileSync(join(sourceRoot, 'AGENTS.md'), '# Shared guidance\n');
+        const agentDefinitionPath = join(sourceRoot, 'docs-agent.md');
+        writeFileSync(
+            agentDefinitionPath,
+            '---\nname: docs-agent\ndescription: fixture agent\n---\n',
+        );
+
+        const copyStats = copyTree(sourceRoot, destinationRoot);
+        const copiedAgentsPath = join(destinationRoot, 'AGENTS.md');
+        const copiedAgentPath = join(destinationRoot, 'docs-agent.md');
+
+        assert.equal(existsSync(copiedAgentsPath), true, 'the canonical instructions install');
+        assert.equal(existsSync(copiedAgentPath), true, 'the real agent definition installs');
+        assert.deepEqual(copyStats.paths, [copiedAgentsPath, copiedAgentPath]);
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+        rmSync(destinationRoot, { recursive: true, force: true });
+    }
+});
+
+
 const SHIPPED_README_NAME = 'README.md';
 const INSTALLED_README_NAME = 'Readme.md';
 const RETIRED_HOOK_RELATIVE_PATH = 'blocking/retired_gate.py';

package/commands/AGENTS.md

@@ -0,0 +1,23 @@
+# commands
+
+Slash-command definitions installed into `~/.claude/commands/` by `bin/install.mjs`. Each `.md` file registers a `/command-name` the user can type in Claude Code. The file name (without `.md`) becomes the command name.
+
+## Command files
+
+| File | Command | What it does |
+|---|---|---|
+| `commit.md` | `/commit` | Commits and pushes changes to GitHub |
+| `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
+| `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
+| `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |
+| `implement.md` | `/implement` | Provides full implementation context to a right-sized engineer in XML format |
+| `plan.md` | `/plan` | Plans a feature through the `anthropic-plan` skill and workflow |
+| `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
+| `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
+| `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
+| `sr-loop.md` | `/sr-loop` | Runs the converging cleanup loop: /simplify passes until clean, then a code-review fix pass |
+| `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
+
+## Format
+
+Each file is plain Markdown. The first paragraph is the command's help text shown in the Claude Code UI. The body is the full instruction set Claude follows when the command runs.

package/commands/CLAUDE.md

@@ -1,23 +1 @@
-# commands
-
-Slash-command definitions installed into `~/.claude/commands/` by `bin/install.mjs`. Each `.md` file registers a `/command-name` the user can type in Claude Code. The file name (without `.md`) becomes the command name.
-
-## Command files
-
-| File | Command | What it does |
-|---|---|---|
-| `commit.md` | `/commit` | Commits and pushes changes to GitHub |
-| `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
-| `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
-| `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |
-| `implement.md` | `/implement` | Provides full implementation context to a right-sized engineer in XML format |
-| `plan.md` | `/plan` | Plans a feature through the `anthropic-plan` skill and workflow |
-| `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
-| `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
-| `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
-| `sr-loop.md` | `/sr-loop` | Runs the converging cleanup loop: /simplify passes until clean, then a code-review fix pass |
-| `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
-
-## Format
-
-Each file is plain Markdown. The first paragraph is the command's help text shown in the Claude Code UI. The body is the full instruction set Claude follows when the command runs.
+@AGENTS.md

package/commands/hook-log-extract.md

@@ -38,9 +38,9 @@ suspected of drift.
 bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --summary
 ```
 
-Skip extraction. Print the top-10 blockers of the last 24 hours with
-their block count and a single truncated command preview, or
-`No new blocks since last run.` when the window is empty.
+Run summary mode to print the top-10 blockers of the last 24 hours with
+their block count and a single truncated command preview. An empty window
+prints `Blocked events recorded in the last 24 hours: 0.`.
 
 ```
 bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --query <name>

package/commands/sr-loop.md

@@ -20,17 +20,21 @@ tool and repeats it until a pass returns zero new findings.
 3. Repeat the invocation. **Skips are sticky:** carry every adjudicated skip
    forward into the next pass as "already adjudicated — do not re-report: ..."
    context, or the loop never converges.
-4. Phase A converges when a full pass returns zero new findings. When the
-   previous pass changed only a line or two, a single combined-lens
-   confirmation agent may serve as the final pass.
+4. Phase A converges when a full pass returns zero new findings, or when a
+   pass's new findings are all nits — doc phrasing, naming, comment altitude,
+   or any fix below a behavior change. On a nit-only pass: apply the fixes,
+   test, commit, push, and stop with no confirming pass. When the previous
+   pass changed only a line or two, a single combined-lens confirmation agent
+   may serve as the final pass.
 
 ## Phase B — loop /code-review low --fix
 
 1. Invoke the `code-review` skill with arguments `low --fix` on the same
    target. Let it report findings and apply its fixes.
 2. After any pass that changed files: test, commit, push as in Phase A.
-3. Repeat until a pass reports zero findings. Phase B usually converges in one
-   pass when Phase A ran first.
+3. Repeat until a pass reports zero findings, or until a pass reports only
+   nits — then fix, test, commit, push, and stop with no confirming pass.
+   Phase B usually converges in one pass when Phase A ran first.
 
 ## Finish
 

package/docs/AGENTS.md

@@ -0,0 +1,32 @@
+# docs
+
+Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. These files are loaded on demand by rules, skills, and agents — they are not always-on context.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `CODE_RULES.md` | Compact agent reference for all code rules; ⚡ marks hook-enforced rules; canonical source agents load before writing code |
+| `TEST_QUALITY.md` | Test writing standards: what to test, what to remove, React testing patterns, anti-patterns |
+| `BDD_DISCOVERY_PROTOCOL.md` | Example Mapping algorithm for discovery before implementation; based on Smart & Molak *BDD in Action* §6.4 |
+| `BDD_SCENARIO_QUALITY.md` | Seven scenario quality patterns (§7.6-style catalog) |
+| `BDD_TEST_LAYOUT.md` | `describe/when/should` test layout and soap-opera personas |
+| `DJANGO_PATTERNS.md` | Django-specific coding patterns |
+| `REACT_PATTERNS.md` | React-specific coding patterns |
+| `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
+| `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
+| `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
+| `wsl-docker-cowork-starter-matrix.md` | Host matrix: WSL/Docker/cowork component → starter → required? → shutdown; policy options with costs; no unmeasured `.wslconfig` memory cap |
+| `host-pool-health-monitor.md` | Operator recipe for Windows pool/handle health: thresholds, clean-shell re-run of `Capture-PoolHealth.ps1`, RC2/RC3/RC4 remediation map |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `references/` | Pointer documents to external sources and standard terminology; loaded on demand |
+
+## Load pattern
+
+A rule points to a doc with the path wrapped in backticks, such as `@~/.claude/docs/<file>.md`. The backticks make it a plain pointer: Claude Code reads the doc only when a rule, skill, or agent opens it, so the doc stays out of session-start context. The same path without backticks expands into context at launch when it sits in a file that loads at session start.
+
+The `InstructionsLoaded` hook confirms this: a bare `@`-import fires an `include` load event; a backtick-wrapped path fires none.

package/docs/CLAUDE.md

@@ -1,33 +1 @@
-# docs
-
-Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. These files are loaded on demand by rules, skills, and agents — they are not always-on context.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `CODE_RULES.md` | Compact agent reference for all code rules; ⚡ marks hook-enforced rules; canonical source agents load before writing code |
-| `TEST_QUALITY.md` | Test writing standards: what to test, what to remove, React testing patterns, anti-patterns |
-| `BDD_DISCOVERY_PROTOCOL.md` | Example Mapping algorithm for discovery before implementation; based on Smart & Molak *BDD in Action* §6.4 |
-| `BDD_SCENARIO_QUALITY.md` | Seven scenario quality patterns (§7.6-style catalog) |
-| `BDD_TEST_LAYOUT.md` | `describe/when/should` test layout and soap-opera personas |
-| `PR_DESCRIPTION_GUIDE.md` | Authoritative reference for the `pr-description-writer` agent; PR body shapes derived from a 120-PR Anthropic corpus |
-| `DJANGO_PATTERNS.md` | Django-specific coding patterns |
-| `REACT_PATTERNS.md` | React-specific coding patterns |
-| `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
-| `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
-| `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
-| `wsl-docker-cowork-starter-matrix.md` | Host matrix: WSL/Docker/cowork component → starter → required? → shutdown; policy options with costs; no unmeasured `.wslconfig` memory cap |
-| `host-pool-health-monitor.md` | Operator recipe for Windows pool/handle health: thresholds, clean-shell re-run of `Capture-PoolHealth.ps1`, RC2/RC3/RC4 remediation map |
-
-## Subdirectory
-
-| Entry | Description |
-|---|---|
-| `references/` | Pointer documents to external sources and standard terminology; loaded on demand |
-
-## Load pattern
-
-A rule points to a doc with the path wrapped in backticks, such as `@~/.claude/docs/<file>.md`. The backticks make it a plain pointer: Claude Code reads the doc only when a rule, skill, or agent opens it, so the doc stays out of session-start context. The same path without backticks expands into context at launch when it sits in a file that loads at session start.
-
-The `InstructionsLoaded` hook confirms this: a bare `@`-import fires an `include` load event; a backtick-wrapped path fires none.
+@AGENTS.md

package/docs/CODE_RULES.md

@@ -1,6 +1,6 @@
 # Code Rules Reference
 
-Compact **projection** of the repository-root canonical policy [`AGENTS.md`](../../../AGENTS.md). When this file and `AGENTS.md` disagree, **`AGENTS.md` wins** — update this projection in the same change.
+Compact **projection** of the checked-in review contract [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md). Update this reference alongside the full review contract when review rules change.
 
 ⚡ marks rules enforced by hand-maintained `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only. Session policy (question routing, task tracking) lives in `rules/*.md`; see [`code-standards.md`](../rules/code-standards.md).
 

package/docs/imagegen.md

@@ -0,0 +1,22 @@
+# Image generation
+
+The canonical image-generation entrypoint lives in the
+`python-automation` repository at `shared_utils.imagegen`.
+
+Resolve `python_automation_root` and `python_exe` from the repository's
+`run/tooling.json`, set `PYTHONPATH` to the resolved root, and run:
+
+```powershell
+$tooling = Get-Content '<REPO>\\run\\tooling.json' | ConvertFrom-Json
+$python_automation_root = $tooling.python_automation_root
+$python_executable = $tooling.python_exe
+$env:PYTHONPATH = $python_automation_root
+
+& $python_executable -m shared_utils.imagegen `
+  --prompt-file <PROMPT.txt> `
+  --size 2880x2880 `
+  --out <IMAGE.png>
+```
+
+Repeat `--reference-image <IMAGE.png>` for up to two visual references.
+The command verifies the decoded PNG dimensions before reporting success.

package/docs/references/AGENTS.md

@@ -0,0 +1,17 @@
+# docs/references
+
+Pointer documents to external sources, standard terminology, and internal tool or skill usage. Files here are loaded on demand by rules that cite them.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
+| `prose-style-enforcement.md` | How `CLAUDE_PROSE_STYLE_ENFORCEMENT` arms opinionated prose gates (default off) while AskUserQuestion lean-block stays always on |
+| `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
+| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and advisor selection |
+| `weak-executor-advisor.md` | Consult profile a below-advisor-tier executor (Sonnet, Haiku) follows on top of `advisor-tool.md`: spawn-prompt steering, context packaging, two-timing rule, consult budget, failure branches |
+
+## Role
+
+A file naming an external concept gives a one-line definition and links a direct source. A file naming an internal tool or skill describes what it does and when to use it. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.

package/docs/references/CLAUDE.md

@@ -1,18 +1 @@
-# docs/references
-
-Pointer documents to external sources, standard terminology, and internal tool or skill usage. Files here are loaded on demand by rules that cite them.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
-| `code-review-enforcement.md` | How the code-review gates work: the two required efforts (push at low, PR creation at xhigh), the stamp bound to the branch-surface hash, the single sanctioned minter, the two-layer stamp-directory guard, and the bypass surfaces the gates leave open |
-| `prose-style-enforcement.md` | How `CLAUDE_PROSE_STYLE_ENFORCEMENT` arms opinionated prose gates (default off) while AskUserQuestion lean-block stays always on |
-| `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
-| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and advisor selection |
-| `weak-executor-advisor.md` | Consult profile a below-advisor-tier executor (Sonnet, Haiku) follows on top of `advisor-tool.md`: spawn-prompt steering, context packaging, two-timing rule, consult budget, failure branches |
-
-## Role
-
-A file naming an external concept gives a one-line definition and links a direct source. A file naming an internal tool or skill describes what it does and when to use it. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.
+@AGENTS.md

package/hooks/AGENTS.md

@@ -0,0 +1,31 @@
+# hooks
+
+Python hook scripts wired into Claude Code's lifecycle via `settings.json`. Each hook answers one or more lifecycle events (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`) and either blocks a tool call, annotates it, or performs a side-effect.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `advisory/` | Hooks that warn but do not block (`permissionDecision: "ask"`) |
+| `blocking/` | Hooks that deny tool calls when a rule is violated |
+| `blocking/config/` | Shared constants for blocking hooks |
+| `diagnostic/` | Hooks that record and extract hook-firing records into Neon |
+| `diagnostic/migrations/` | SQL migrations for the `hook_events` Neon schema |
+| `diagnostic/queries/` | Parameterized SQL queries for inspecting blocked commands |
+| `git-hooks/` | Native git hooks (`pre-commit`, `pre-push`, `post-commit`) installed via the git-hooks path |
+| `git-hooks/git_hooks_constants/` | Shared constants for the git-hook scripts |
+| `hooks_constants/` | Shared constant modules imported by multiple hooks across this tree (includes `pii_prevention_constants.py` for personal-data and secret scan patterns) |
+| `lifecycle/` | Hooks that run at session or config-change boundaries |
+| `observability/` | PostToolUse hooks that record agent behavior for diagnostics |
+| `session/` | SessionStart and SessionEnd hooks for per-session cleanup |
+| `validation/` | PostToolUse hooks that validate code quality after a write (mypy, auto-format) |
+| `validators/` | Library modules used by the validation hooks — checks split by concern |
+| `workflow/` | PostToolUse hooks that trigger doc publishing and companion-file generation |
+
+## Conventions
+
+- **Event mapping:** Every hook reads JSON from stdin and exits 0 (allow) or prints a `hookSpecificOutput` block (block/ask). Blocking hooks set `permissionDecision: "block"`.
+- **Constants companion:** Each hook with more than a handful of tunable strings keeps them in a `hooks_constants/<hook_name>_constants.py` sibling. Import from there; do not repeat literals.
+- **Tests:** Each hook has one or more `test_<hookname>*.py` files beside it. Run with `python -m pytest <test_file>`.
+- **Registration:** Hooks are declared in `settings.json` under the right lifecycle event. The installer (`packages/claude-dev-env/bin/install.mjs`) merges the hook entries during `npx claude-dev-env`.
+- **Top-level utilities:** `_gh_pr_author_swap_utils.py` and `rewrite_plugin_paths.py` are shared helpers imported by multiple blocking hooks. `hooks.json` records the canonical hook-to-event mapping for auditing.

package/hooks/CLAUDE.md

@@ -1,31 +1 @@
-# hooks
-
-Python hook scripts wired into Claude Code's lifecycle via `settings.json`. Each hook answers one or more lifecycle events (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`) and either blocks a tool call, annotates it, or performs a side-effect.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `advisory/` | Hooks that warn but do not block (`permissionDecision: "ask"`) |
-| `blocking/` | Hooks that deny tool calls when a rule is violated |
-| `blocking/config/` | Shared constants for the verified-commit gate family |
-| `diagnostic/` | Hooks that record and extract hook-firing records into Neon |
-| `diagnostic/migrations/` | SQL migrations for the `hook_events` Neon schema |
-| `diagnostic/queries/` | Parameterized SQL queries for inspecting blocked commands |
-| `git-hooks/` | Native git hooks (`pre-commit`, `pre-push`, `post-commit`) installed via the git-hooks path |
-| `git-hooks/git_hooks_constants/` | Shared constants for the git-hook scripts |
-| `hooks_constants/` | Shared constant modules imported by multiple hooks across this tree (includes `pii_prevention_constants.py` for personal-data and secret scan patterns) |
-| `lifecycle/` | Hooks that run at session or config-change boundaries |
-| `observability/` | PostToolUse hooks that record agent behavior for diagnostics |
-| `session/` | SessionStart and SessionEnd hooks for per-session cleanup |
-| `validation/` | PostToolUse hooks that validate code quality after a write (mypy, auto-format) |
-| `validators/` | Library modules used by the validation hooks — checks split by concern |
-| `workflow/` | PostToolUse hooks that trigger doc publishing and companion-file generation |
-
-## Conventions
-
-- **Event mapping:** Every hook reads JSON from stdin and exits 0 (allow) or prints a `hookSpecificOutput` block (block/ask). Blocking hooks set `permissionDecision: "block"`.
-- **Constants companion:** Each hook with more than a handful of tunable strings keeps them in a `hooks_constants/<hook_name>_constants.py` sibling. Import from there; do not repeat literals.
-- **Tests:** Each hook has one or more `test_<hookname>*.py` files beside it. Run with `python -m pytest <test_file>`.
-- **Registration:** Hooks are declared in `settings.json` under the right lifecycle event. The installer (`packages/claude-dev-env/bin/install.mjs`) merges the hook entries during `npx claude-dev-env`.
-- **Top-level utilities:** `_gh_pr_author_swap_utils.py` and `rewrite_plugin_paths.py` are shared helpers imported by multiple blocking hooks. `hooks.json` records the canonical hook-to-event mapping for auditing.
+@AGENTS.md

package/hooks/_gh_pr_author_swap_utils.py

@@ -155,6 +155,20 @@ def _switch_gh_account(to_account: str) -> bool:
     return completed_process.returncode == 0
 
 
+def _build_restore_failure_message(
+    hook_label: str,
+    original_account: str,
+    state_file: Path,
+    state_file_context: str,
+) -> str:
+    """Build the shared diagnostic for a failed account restoration."""
+    return (
+        f"[{hook_label}] Restore the gh account to {original_account!r}; "
+        f"gh account switch requires attention for {state_file_context} {state_file}. "
+        "The file remains for the next session."
+    )
+
+
 def _read_original_account(state_file: Path) -> str | None:
     """Read the original-account login from a swap-state file.
 

package/hooks/advisory/AGENTS.md

@@ -0,0 +1,16 @@
+# hooks/advisory
+
+Hooks that produce a warning prompt (`permissionDecision: "ask"`) rather than an outright block. The user sees the warning and can continue or cancel.
+
+## Key files
+
+| File | Event | What it guards |
+|---|---|---|
+| `migration_safety_advisor.py` | PreToolUse (Write/Edit) | Django migration files containing `RemoveField`, `RenameField`, `DeleteModel`, or `RenameModel` — warns that these operations must be backwards-compatible during deployment |
+| `refactor_guard.py` | PreToolUse (Edit) | Edits that rename or restructure existing code not present in the current git diff — warns that the change may be out of scope |
+
+## Conventions
+
+- Both hooks exit 0 (silent) when their trigger condition is not met.
+- `refactor_guard.py` respects a bypass token at `~/.claude/.refactor-bypass-token`; when that file exists the hook stays silent.
+- Tests live beside each hook following the `test_<name>.py` pattern used in `blocking/`. Run with `python -m pytest <test_file>`.

package/hooks/advisory/CLAUDE.md

@@ -1,16 +1 @@
-# hooks/advisory
-
-Hooks that produce a warning prompt (`permissionDecision: "ask"`) rather than an outright block. The user sees the warning and can continue or cancel.
-
-## Key files
-
-| File | Event | What it guards |
-|---|---|---|
-| `migration_safety_advisor.py` | PreToolUse (Write/Edit) | Django migration files containing `RemoveField`, `RenameField`, `DeleteModel`, or `RenameModel` — warns that these operations must be backwards-compatible during deployment |
-| `refactor_guard.py` | PreToolUse (Edit) | Edits that rename or restructure existing code not present in the current git diff — warns that the change may be out of scope |
-
-## Conventions
-
-- Both hooks exit 0 (silent) when their trigger condition is not met.
-- `refactor_guard.py` respects a bypass token at `~/.claude/.refactor-bypass-token`; when that file exists the hook stays silent.
-- Tests live beside each hook following the `test_<name>.py` pattern used in `blocking/`. Run with `python -m pytest <test_file>`.
+@AGENTS.md