claude-dev-env 1.93.1 → 1.95.0

package/bin/install.prune.test.mjs

@@ -0,0 +1,457 @@
+import { test, after } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import {
+    mkdtempSync,
+    mkdirSync,
+    writeFileSync,
+    existsSync,
+    readFileSync,
+    readdirSync,
+    rmSync,
+    cpSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+const EXCLUDED_PACKAGE_COPY_DIRECTORY = 'node_modules';
+
+const RETIRED_SKILL_DIRECTORIES = [
+    'findbugs',
+    'fixbugs',
+    'pr-scope-resolve',
+    'post-audit-findings',
+    'pr-consistency-audit',
+    'bdd-protocol',
+];
+const PERSONAL_SKILL_DIRECTORIES = ['balatro', 'midjourney-sref', 'credit-card-picker'];
+const SHIPPED_SKILL_DIRECTORY = 'autoconverge';
+const PRUNED_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
+const SKIP_PRUNE_NOTICE_MARKER = 'Skipping retired-skill prune';
+const DEPENDENCY_STUB_PACKAGE_SEGMENTS = ['@jl-cmd', 'prompt-generator'];
+
+/**
+ * Create a stub node_modules tree the installer can resolve the declared
+ * dependency package from, and return its root for the child's NODE_PATH.
+ *
+ * The installer resolves `@jl-cmd/prompt-generator/package.json`; a lone
+ * package.json at that path is enough for `createRequire.resolve` to succeed.
+ * The stub makes the dependency resolvable inside the sandbox so a full install
+ * exercises the real prune path. It does not prove the real private package
+ * resolves in a real install — CI cannot host that package — only that the
+ * resolved-dependency branch prunes as designed.
+ *
+ * @param {string} homeDirectory The sandbox home the stub is nested under.
+ * @returns {string} The stub modules root to place on the child's NODE_PATH.
+ */
+let isolatedInstallerPath = null;
+let isolatedPackageCopyRoot = null;
+
+/**
+ * Copy the package into a temp directory without node_modules and return the
+ * copy's installer path.
+ *
+ * The installer resolves its declared dependencies with Node's regular
+ * node_modules walk starting at its own file, so the real installer under the
+ * repo always finds `@jl-cmd/prompt-generator` once `npm install` has run —
+ * removing NODE_PATH from the child cannot make the dependency unresolvable
+ * there. Running the copy makes resolution genuinely fail through the
+ * installer's own catch path: no node_modules sits in the copy's ancestry and
+ * the child gets no NODE_PATH. The copy is created once and shared by every
+ * unresolved-dependency install; installs write only into their sandbox HOME.
+ *
+ * @returns {string} The path to `bin/install.mjs` inside the package copy.
+ */
+function ensureIsolatedInstallerPath() {
+    if (isolatedInstallerPath !== null) return isolatedInstallerPath;
+    isolatedPackageCopyRoot = mkdtempSync(join(tmpdir(), 'cdev-prune-package-'));
+    cpSync(PACKAGE_DIRECTORY, isolatedPackageCopyRoot, {
+        recursive: true,
+        filter: sourcePath => basename(sourcePath) !== EXCLUDED_PACKAGE_COPY_DIRECTORY,
+    });
+    isolatedInstallerPath = join(isolatedPackageCopyRoot, 'bin', 'install.mjs');
+    return isolatedInstallerPath;
+}
+
+after(() => {
+    if (isolatedPackageCopyRoot !== null) {
+        rmSync(isolatedPackageCopyRoot, { recursive: true, force: true });
+    }
+});
+
+function ensureDependencyStub(homeDirectory) {
+    const stubModulesRoot = join(homeDirectory, 'dependency-stub-modules');
+    const stubPackageDirectory = join(stubModulesRoot, ...DEPENDENCY_STUB_PACKAGE_SEGMENTS);
+    mkdirSync(stubPackageDirectory, { recursive: true });
+    writeFileSync(
+        join(stubPackageDirectory, 'package.json'),
+        JSON.stringify({
+            name: DEPENDENCY_STUB_PACKAGE_SEGMENTS.join('/'),
+            version: '1.0.0',
+            description: 'sandbox dependency stub',
+        }) + '\n',
+    );
+    return stubModulesRoot;
+}
+
+/**
+ * Report whether a retired skill directory landed under the prune backup root.
+ *
+ * @param {string} claudeDirectory The sandbox ~/.claude directory.
+ * @param {string} skillName The retired skill directory name to look for.
+ * @returns {boolean} True when a timestamped backup holds the skill directory.
+ */
+function prunedBackupContains(claudeDirectory, skillName) {
+    const backupRoot = join(claudeDirectory, PRUNED_BACKUP_DIRECTORY_NAME);
+    if (!existsSync(backupRoot)) return false;
+    return readdirSync(backupRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .some(timestampDir => existsSync(join(backupRoot, timestampDir.name, skillName)));
+}
+
+/**
+ * Create an isolated ~/.claude sandbox and return the paths a prune test reads.
+ *
+ * The returned home directory becomes the installer's HOME, so every file the
+ * install writes and every skill directory the prune inspects stays inside the
+ * temp tree and never touches the machine's real ~/.claude.
+ *
+ * @returns {{homeDirectory: string, claudeDirectory: string, skillsDirectory: string, manifestPath: string}}
+ */
+function createSandbox() {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-prune-home-'));
+    const claudeDirectory = join(homeDirectory, '.claude');
+    const skillsDirectory = join(claudeDirectory, 'skills');
+    mkdirSync(skillsDirectory, { recursive: true });
+    const manifestPath = join(claudeDirectory, '.claude-dev-env-manifest.json');
+    return { homeDirectory, claudeDirectory, skillsDirectory, manifestPath };
+}
+
+/**
+ * Plant a skill directory under the sandbox with a single marker file.
+ *
+ * A personal directory is planted with no ``SKILL.md`` so it never looks like a
+ * shipped skill; a retired directory is planted with a ``SKILL.md`` so it mirrors
+ * a real skill the package once installed and later dropped.
+ *
+ * @param {string} skillsDirectory The sandbox skills directory.
+ * @param {string} skillName The directory name to plant.
+ * @param {boolean} withSkillManifest Whether to write a ``SKILL.md`` marker.
+ */
+function plantSkillDirectory(skillsDirectory, skillName, withSkillManifest) {
+    const skillDirectory = join(skillsDirectory, skillName);
+    mkdirSync(skillDirectory, { recursive: true });
+    const markerName = withSkillManifest ? 'SKILL.md' : 'notes.md';
+    writeFileSync(join(skillDirectory, markerName), `seeded ${skillName}\n`);
+}
+
+/**
+ * Run the real installer against the sandbox home and return its stdout.
+ *
+ * The declared dependency package is resolvable by default: the child's
+ * NODE_PATH points at a sandbox stub so `createRequire.resolve` finds it and the
+ * full-install prune runs. Passing ``{ dependencyResolvable: false }`` runs the
+ * installer from an isolated package copy with no node_modules in its ancestry
+ * and no NODE_PATH, so the dependency fails to resolve and the installer skips
+ * the prune.
+ *
+ * @param {string} homeDirectory The sandbox home the installer writes into.
+ * @param {string[]} extraArguments Installer arguments (for example ``['--only', 'core']``).
+ * @param {{dependencyResolvable?: boolean}} options Whether the dependency resolves.
+ * @returns {string} The installer's stdout.
+ */
+function runInstaller(homeDirectory, extraArguments, options = {}) {
+    const dependencyResolvable = options.dependencyResolvable !== false;
+    const childEnvironment = {
+        ...process.env,
+        HOME: homeDirectory,
+        USERPROFILE: homeDirectory,
+        GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+    };
+    let installerPath;
+    if (dependencyResolvable) {
+        childEnvironment.NODE_PATH = ensureDependencyStub(homeDirectory);
+        installerPath = INSTALLER_PATH;
+    } else {
+        delete childEnvironment.NODE_PATH;
+        installerPath = ensureIsolatedInstallerPath();
+    }
+    return execFileSync('node', [installerPath, ...extraArguments], {
+        cwd: dirname(installerPath),
+        encoding: 'utf8',
+        env: childEnvironment,
+    });
+}
+
+function readManifest(manifestPath) {
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+test('a full reinstall over a pre-manifest dirty tree prunes retired skills and keeps personal ones', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+        for (const personalSkill of PERSONAL_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, personalSkill, false);
+        }
+        assert.equal(existsSync(sandbox.manifestPath), false, 'sandbox starts with no manifest');
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                false,
+                `retired skill ${retiredSkill} should be pruned`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                true,
+                `retired skill ${retiredSkill} should be moved to the prune backup`,
+            );
+        }
+        for (const personalSkill of PERSONAL_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, personalSkill)),
+                true,
+                `personal skill ${personalSkill} should survive`,
+            );
+        }
+        assert.equal(
+            existsSync(join(sandbox.skillsDirectory, SHIPPED_SKILL_DIRECTORY)),
+            true,
+            'shipped skills should install',
+        );
+        const manifest = readManifest(sandbox.manifestPath);
+        assert.ok(Array.isArray(manifest.skills), 'manifest gains a skills array');
+        assert.ok(manifest.skills.includes(SHIPPED_SKILL_DIRECTORY), 'manifest skills lists shipped skills');
+        assert.equal(manifest.skills.includes('_shared'), false, 'manifest skills omits _shared');
+        assert.equal(manifest.skills.includes('__pycache__'), false, 'manifest skills omits __pycache__');
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall over an old-format manifest without a skills key still prunes via the ever-shipped fallback', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+        writeFileSync(
+            sandbox.manifestPath,
+            JSON.stringify({
+                package: 'claude-dev-env',
+                version: '0.0.0',
+                installedAt: new Date().toISOString(),
+                files: [join(sandbox.skillsDirectory, 'findbugs', 'SKILL.md')],
+            }, null, 2) + '\n',
+        );
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                false,
+                `retired skill ${retiredSkill} should be pruned via the ever-shipped fallback`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                true,
+                `retired skill ${retiredSkill} should be moved to the prune backup`,
+            );
+        }
+        const manifest = readManifest(sandbox.manifestPath);
+        assert.ok(Array.isArray(manifest.skills), 'the reinstall writes the skills key onto the old-format manifest');
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall prunes a manifest-recorded skill absent from the package and keeps a personal directory', () => {
+    const sandbox = createSandbox();
+    try {
+        const retiredManifestSkill = 'ghost-skill';
+        const personalSkill = 'balatro';
+        plantSkillDirectory(sandbox.skillsDirectory, retiredManifestSkill, true);
+        plantSkillDirectory(sandbox.skillsDirectory, personalSkill, false);
+        writeFileSync(
+            sandbox.manifestPath,
+            JSON.stringify({
+                package: 'claude-dev-env',
+                version: '0.0.0',
+                installedAt: new Date().toISOString(),
+                files: [],
+                skills: [SHIPPED_SKILL_DIRECTORY, retiredManifestSkill],
+            }, null, 2) + '\n',
+        );
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        assert.equal(
+            existsSync(join(sandbox.skillsDirectory, retiredManifestSkill)),
+            false,
+            'a skill the prior manifest recorded but the package no longer ships is pruned',
+        );
+        assert.equal(
+            prunedBackupContains(sandbox.claudeDirectory, retiredManifestSkill),
+            true,
+            'the manifest-recorded retired skill is moved to the prune backup',
+        );
+        assert.equal(
+            existsSync(join(sandbox.skillsDirectory, personalSkill)),
+            true,
+            'a personal directory in neither the manifest nor the ever-shipped set survives',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a scoped --only install leaves retired skills in place because prune runs on full installs only', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+
+        runInstaller(sandbox.homeDirectory, ['--only', 'core']);
+
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                true,
+                `retired skill ${retiredSkill} should survive a scoped install`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                false,
+                `retired skill ${retiredSkill} should not be moved to backup by a scoped install`,
+            );
+        }
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall keeps pr-fix-protocol because the package ships it again', () => {
+    const sandbox = createSandbox();
+    try {
+        plantSkillDirectory(sandbox.skillsDirectory, 'pr-fix-protocol', true);
+        writeFileSync(join(sandbox.skillsDirectory, 'pr-fix-protocol', 'SKILL.md'), 'stale seeded copy\n');
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolvable-dependency install runs the prune rather than skipping it',
+        );
+        const restoredSkillPath = join(sandbox.skillsDirectory, 'pr-fix-protocol', 'SKILL.md');
+        assert.equal(existsSync(restoredSkillPath), true, 'pr-fix-protocol survives and is reinstalled');
+        assert.notEqual(
+            readFileSync(restoredSkillPath, 'utf8'),
+            'stale seeded copy\n',
+            'the shipped pr-fix-protocol overwrites the stale seeded copy',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall with an unresolved dependency skips the prune and leaves retired skills untouched', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+
+        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
+
+        assert.equal(
+            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            true,
+            'the installer logs a notice that it is skipping the prune',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                true,
+                `retired skill ${retiredSkill} should survive when a dependency is unresolved`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                false,
+                `retired skill ${retiredSkill} should not be moved to backup when the prune is skipped`,
+            );
+        }
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('the prune skip is scoped: once the dependency resolves a later full install prunes normally', () => {
+    const sandbox = createSandbox();
+    try {
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            plantSkillDirectory(sandbox.skillsDirectory, retiredSkill, true);
+        }
+
+        const skippedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
+        assert.equal(
+            skippedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            true,
+            'the unresolved-dependency install skips the prune',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                true,
+                `retired skill ${retiredSkill} should still be present after the skipped prune`,
+            );
+        }
+
+        const resolvedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: true });
+        assert.equal(
+            resolvedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            false,
+            'the resolved-dependency install runs the prune, proving the skip is not a permanent disable',
+        );
+        for (const retiredSkill of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(
+                existsSync(join(sandbox.skillsDirectory, retiredSkill)),
+                false,
+                `retired skill ${retiredSkill} should be pruned once the dependency resolves`,
+            );
+            assert.equal(
+                prunedBackupContains(sandbox.claudeDirectory, retiredSkill),
+                true,
+                `retired skill ${retiredSkill} should be moved to the prune backup on the resolved install`,
+            );
+        }
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.test.mjs

@@ -637,6 +637,12 @@ test('commandReferencesManagedHook leaves an unmanaged inline -c command that im
 });
 
 
+
+function isPreToolUseDispatcherCommand(command) {
+    // Basename-anchored match: bash_pre_tool_use_dispatcher.py must not count.
+    return /(?:^|[/\\])pre_tool_use_dispatcher\.py(?![A-Za-z0-9_])/.test(command);
+}
+
 function countManagedRunAllValidatorsHooks(settings) {
     const writeEditGroups = (settings.hooks.PreToolUse || []).filter(
         group => group.matcher === 'Write|Edit'
@@ -996,7 +1002,7 @@ test('mergeHooksIntoSettings into old folded-hooks settings yields exactly one d
     const allPreToolUseGroups = settings.hooks.PreToolUse || [];
     const allHookCommands = allPreToolUseGroups.flatMap(group => group.hooks.map(hook => hook.command));
 
-    const allDispatcherCommands = allHookCommands.filter(cmd => cmd.includes('pre_tool_use_dispatcher.py'));
+    const allDispatcherCommands = allHookCommands.filter(isPreToolUseDispatcherCommand);
     assert.equal(allDispatcherCommands.length, 1, 'exactly one dispatcher entry must be present');
 
     for (const foldedPath of FOLDED_HOOK_RELATIVE_PATHS) {
@@ -1029,7 +1035,7 @@ test('mergeHooksIntoSettings is idempotent when run twice against an already-upd
     const allPreToolUseGroups = settings.hooks.PreToolUse || [];
     const allHookCommands = allPreToolUseGroups.flatMap(group => group.hooks.map(hook => hook.command));
 
-    const allDispatcherCommands = allHookCommands.filter(cmd => cmd.includes('pre_tool_use_dispatcher.py'));
+    const allDispatcherCommands = allHookCommands.filter(isPreToolUseDispatcherCommand);
     assert.equal(allDispatcherCommands.length, 1, 'dispatcher must appear exactly once after two merges');
     assert.equal(countManagedRunAllValidatorsHooks(settings), 1, 'run_all_validators must appear exactly once after two merges');
 });
@@ -1042,7 +1048,7 @@ test('shipped hooks.json matches the dispatcher design: dispatchers registered,
 
     const allPreToolUseGroups = shippedHooksConfig.hooks.PreToolUse || [];
     const allPreCommands = allPreToolUseGroups.flatMap(group => group.hooks.map(hook => hook.command));
-    const preDispatcherCommands = allPreCommands.filter(cmd => cmd.includes('pre_tool_use_dispatcher.py'));
+    const preDispatcherCommands = allPreCommands.filter(isPreToolUseDispatcherCommand);
     assert.equal(preDispatcherCommands.length, 1, 'shipped hooks.json must register the PreToolUse dispatcher exactly once');
 
     assert.equal(
@@ -1222,6 +1228,6 @@ test('mergeHooksIntoSettings prunes the inline run_all_validators runner when th
     }
 
     const dispatcherGroup = settings.hooks.PreToolUse.find(group => group.matcher === 'Write|Edit|MultiEdit');
-    const dispatcherCommands = dispatcherGroup.hooks.filter(hook => hook.command.includes('pre_tool_use_dispatcher.py'));
+    const dispatcherCommands = dispatcherGroup.hooks.filter(hook => isPreToolUseDispatcherCommand(hook.command));
     assert.equal(dispatcherCommands.length, 1, 'the PreToolUse dispatcher must remain exactly once');
 });

package/docs/CODE_RULES.md

@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.

package/hooks/blocking/CLAUDE.md

@@ -81,6 +81,8 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
 | `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
+| `pii_commit_command.py` | library | Token-aware git-commit detection reused by `pii_prevention_blocker.py` |
+| `pii_payload_scan.py` | library | Write/Edit and durable post-body PII evaluation reused by `pii_prevention_blocker.py` |
 | `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Content that carries high-confidence personal data or secrets (real emails, home-dir paths, private IPs, credential material) on write, durable GitHub posts, or staged commit paths |
 | `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |

package/hooks/blocking/code_rules_enforcer.py

@@ -158,6 +158,7 @@ from code_rules_shared import (  # noqa: E402
     is_ephemeral_script_path,
     is_hook_infrastructure,
     is_test_file,
+    is_under_session_scratchpad,
 )
 from code_rules_string_magic import (  # noqa: E402
     check_inline_literal_collections,
@@ -1104,6 +1105,9 @@ def main(all_arguments: list[str]) -> None:
     tool_input = pretooluse_payload.get("tool_input", {})
     file_path = tool_input.get("file_path", "")
 
+    if is_under_session_scratchpad(file_path, pretooluse_payload):
+        sys.exit(0)
+
     runs_full_verdict = _is_validated_target(file_path)
     if not runs_full_verdict and not _is_hook_infrastructure_python_target(file_path):
         sys.exit(0)

package/hooks/blocking/code_rules_shared.py

@@ -4,6 +4,7 @@ import ast
 import difflib
 import os
 import sys
+import tempfile
 from collections.abc import Collection, Iterator
 from pathlib import Path
 
@@ -29,6 +30,13 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     LEADING_DRIVE_LETTER_PATTERN,
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
+from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+    HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT,
+    HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
+    HOOK_PAYLOAD_SESSION_ID_KEY,
+    HOOK_PAYLOAD_WORKING_DIRECTORY_KEY,
+)
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
     TYPE_CHECKING_IDENTIFIER,
 )
@@ -267,6 +275,80 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     return False
 
 
+def _resolve_session_scratchpad_root(hook_payload: dict) -> str | None:
+    """Rebuild the harness session scratchpad directory from a PreToolUse payload.
+
+    ::
+
+        payload.cwd = /home/user/project    payload.session_id = 5f2c...
+                          |                            |
+        <tempdir>/claude-<uid>/-home-user-project/5f2c.../scratchpad
+                     |               |
+                  os.getuid()   cwd with each "/" turned to "-"
+
+    No environment variable carries this path, so it is rebuilt from the three
+    signals a hook can read: the POSIX user id and the ``cwd`` and ``session_id``
+    fields the harness puts in every PreToolUse payload. The rebuilt directory
+    is returned only when it exists on disk, so a wrong guess or a non-POSIX
+    platform yields None and the gates keep full enforcement.
+
+    Args:
+        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+
+    Returns:
+        The scratchpad directory path when it exists on disk, else None.
+    """
+    get_user_id = getattr(os, "getuid", None)
+    if get_user_id is None:
+        return None
+    session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
+    working_directory = hook_payload.get(HOOK_PAYLOAD_WORKING_DIRECTORY_KEY, "")
+    if not isinstance(session_id, str) or not session_id:
+        return None
+    if not isinstance(working_directory, str) or not working_directory:
+        return None
+    mangled_working_directory = working_directory.replace("\\", "/").replace(
+        "/", HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT
+    )
+    user_directory_name = f"{HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX}{get_user_id()}"
+    scratchpad_root = os.path.join(
+        tempfile.gettempdir(),
+        user_directory_name,
+        mangled_working_directory,
+        session_id,
+        HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    )
+    if not os.path.isdir(scratchpad_root):
+        return None
+    return scratchpad_root
+
+
+def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
+    """Return True when file_path resolves under the harness session scratchpad.
+
+    One-off scripts written to the session scratchpad are throwaway tooling
+    outside every repo, so the TDD and CODE_RULES gates skip them. Both
+    file_path and the rebuilt scratchpad root are resolved through the real
+    filesystem (symlinks followed) before the containment test, so a symlink
+    into the scratchpad exempts and a symlink out of it does not.
+
+    Args:
+        file_path: The path the write targets.
+        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+
+    Returns:
+        True when file_path's real path sits at or under the session scratchpad.
+    """
+    if not file_path:
+        return False
+    scratchpad_root = _resolve_session_scratchpad_root(hook_payload)
+    if scratchpad_root is None:
+        return False
+    real_target = os.path.realpath(file_path)
+    real_root = os.path.realpath(scratchpad_root)
+    return real_target == real_root or real_target.startswith(real_root + os.sep)
+
+
 def is_migration_file(file_path: str) -> bool:
     """Check if file is a Django migration (must be self-contained)."""
     path_lower = file_path.lower().replace("\\", "/")

package/hooks/blocking/code_rules_test_layout.py

@@ -133,7 +133,11 @@ def _referenced_names(tree: ast.Module) -> set[str]:
     }
     return load_names | literal_values
 
-def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> list[str]:
+def _dead_constant_messages(
+    tree: ast.Module,
+    referenced_names: set[str],
+    maximum_issues: int,
+) -> list[str]:
     """Return one message per module constant absent from the referenced set."""
     issues: list[str] = []
     for each_name, each_line in _module_constant_targets(tree):
@@ -142,7 +146,7 @@ def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> lis
         issues.append(
             f"Line {each_line}: constant {each_name!r} - {DEAD_TEST_CONSTANT_GUIDANCE}"
         )
-        if len(issues) >= MAX_TEST_LAYOUT_ISSUES:
+        if len(issues) >= maximum_issues:
             break
     return issues
 
@@ -174,7 +178,9 @@ def check_dead_test_module_constant(content: str, file_path: str) -> list[str]:
     tree = _parse_module(content)
     if tree is None:
         return []
-    return _dead_constant_messages(tree, _referenced_names(tree))
+    return _dead_constant_messages(
+        tree, _referenced_names(tree), MAX_TEST_LAYOUT_ISSUES
+    )
 
 def _node_names_fixture(node: ast.AST) -> bool:
     """Return whether one decorator sub-node spells the pytest fixture marker."""