claude-dev-env 2.16.0 → 2.17.0

package/bin/install.prune.test.mjs

@@ -1,4 +1,4 @@
-import { test, after } from 'node:test';
+import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
 import { execFileSync, spawnSync } from 'node:child_process';
 import {
@@ -9,7 +9,6 @@ import {
     readFileSync,
     readdirSync,
     rmSync,
-    cpSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, basename } from 'node:path';
@@ -28,21 +27,15 @@ const RETIRED_SKILL_DIRECTORIES = [
     'pr-consistency-audit',
     'bdd-protocol',
 ];
-const PERSONAL_SKILL_DIRECTORIES = ['balatro', 'midjourney-sref', 'credit-card-picker'];
+const PERSONAL_SKILL_DIRECTORIES = ['credit-card-picker', 'midjourney-sref'];
 const SHIPPED_SKILL_DIRECTORY = 'autoconverge';
 const PRUNED_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
 const SKIP_PRUNE_NOTICE_MARKER = 'Skipping retired-skill and stale-file prune';
 const STALE_SKILL_FILE_RELATIVE_SEGMENTS = ['scripts', 'retired_module.py'];
 const RUNTIME_ARTIFACT_RELATIVE_SEGMENTS = ['scripts', '__pycache__', 'helper.cpython-312.pyc'];
-const DEPENDENCY_STUB_PACKAGE_SEGMENTS = ['@jl-cmd', 'prompt-generator'];
-const DEPENDENCY_SUPPLIED_SKILL_DIRECTORY = 'dependency-supplied-skill';
 const SCOPED_GROUP_SKILL_DIRECTORY = 'orchestrator';
 const CORE_REVIEW_GUIDE_SKILL_DIRECTORIES = [
     'small-cl',
-    'comments',
-    'reviews',
-    'descriptions',
-    'emergencies',
 ];
 const PRIOR_RUN_BACKUP_DIRECTORY_NAMES = [
     '2020-01-01T00-00-00-000Z',
@@ -70,70 +63,6 @@ const NESTED_SKILL_FILE_SEGMENTS = [NESTED_SKILL_DIRECTORY, 'scripts', 'a.py'];
 const MYPY_INI_FILE_NAME = '.mypy.ini';
 const SKIPPED_RECORD_SUMMARY_MARKER = 'manifest record(s) skipped';
 
-/**
- * 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 path under one managed root landed in a run backup.
  *
@@ -203,20 +132,12 @@ function plantSkillDirectory(skillsDirectory, skillName, withSkillManifest) {
 /**
  * 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 { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory, options);
+function runInstaller(homeDirectory, extraArguments) {
+    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory);
     return execFileSync('node', [installerPath, ...extraArguments], {
         cwd: dirname(installerPath),
         encoding: 'utf8',
@@ -228,11 +149,9 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
  * Build the installer path and child environment one sandbox run uses.
  *
  * @param {string} homeDirectory The sandbox home the installer writes into.
- * @param {{dependencyResolvable?: boolean}} options Whether the dependency resolves.
  * @returns {{installerPath: string, childEnvironment: object}} The invocation inputs.
  */
-function resolveInstallerInvocation(homeDirectory, options) {
-    const dependencyResolvable = options.dependencyResolvable !== false;
+function resolveInstallerInvocation(homeDirectory) {
     const childEnvironment = {
         ...process.env,
         HOME: homeDirectory,
@@ -240,12 +159,7 @@ function resolveInstallerInvocation(homeDirectory, options) {
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
         CODEX_HOME: join(homeDirectory, '.codex'),
     };
-    if (dependencyResolvable) {
-        childEnvironment.NODE_PATH = ensureDependencyStub(homeDirectory);
-        return { installerPath: INSTALLER_PATH, childEnvironment };
-    }
-    delete childEnvironment.NODE_PATH;
-    return { installerPath: ensureIsolatedInstallerPath(), childEnvironment };
+    return { installerPath: INSTALLER_PATH, childEnvironment };
 }
 
 /**
@@ -259,7 +173,7 @@ function resolveInstallerInvocation(homeDirectory, options) {
  * @returns {string} The child's stdout and stderr, joined.
  */
 function runInstallerReadingBothStreams(homeDirectory, extraArguments) {
-    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory, {});
+    const { installerPath, childEnvironment } = resolveInstallerInvocation(homeDirectory);
     const completedRun = spawnSync('node', [installerPath, ...extraArguments], {
         cwd: dirname(installerPath),
         encoding: 'utf8',
@@ -634,7 +548,7 @@ test('a full reinstall prunes a manifest-recorded skill absent from the package
     const sandbox = createSandbox();
     try {
         const retiredManifestSkill = 'ghost-skill';
-        const personalSkill = 'balatro';
+        const personalSkill = 'credit-card-picker';
         plantSkillDirectory(sandbox.skillsDirectory, retiredManifestSkill, true);
         plantSkillDirectory(sandbox.skillsDirectory, personalSkill, false);
         writeFileSync(
@@ -701,115 +615,25 @@ test('a scoped --only install leaves retired skills in place because prune runs
     }
 });
 
-test('a full reinstall keeps pr-fix-protocol because the package ships it again', () => {
+test('a full reinstall keeps autoconverge 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');
+        plantSkillDirectory(sandbox.skillsDirectory, 'autoconverge', true);
+        writeFileSync(join(sandbox.skillsDirectory, 'autoconverge', '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',
+            'the full 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');
+        const restoredSkillPath = join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md');
+        assert.equal(existsSync(restoredSkillPath), true, 'autoconverge 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(
-                prunedSkillBackupContains(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('a full install that holds the prune keeps prior manifest file entries it did not itself write', () => {
-    const sandbox = createSandbox();
-    try {
-        runInstaller(sandbox.homeDirectory, []);
-        const { staleFilePath } = seedStaleSkillFile(sandbox);
-        const filesBeforeHeldPrune = readManifest(sandbox.manifestPath).files;
-
-        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
-
-        assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            true,
-            'the unresolved-dependency install holds both prunes',
-        );
-        const recordedFiles = new Set(readManifest(sandbox.manifestPath).files);
-        assert.equal(
-            recordedFiles.has(staleFilePath),
-            true,
-            'the entry a later pruning install needs to spot the stale file stays on the record',
-        );
-        const droppedEntries = filesBeforeHeldPrune.filter(priorPath => !recordedFiles.has(priorPath));
-        assert.deepEqual(droppedEntries, [], 'a held prune drops no prior file entry');
-    } finally {
-        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
-    }
-});
-
-test('a full install that holds the prune keeps prior manifest skill names it did not itself install', () => {
-    const sandbox = createSandbox();
-    try {
-        runInstaller(sandbox.homeDirectory, []);
-        plantSkillDirectory(sandbox.skillsDirectory, DEPENDENCY_SUPPLIED_SKILL_DIRECTORY, true);
-        const manifest = readManifest(sandbox.manifestPath);
-        manifest.skills.push(DEPENDENCY_SUPPLIED_SKILL_DIRECTORY);
-        writeFileSync(sandbox.manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-
-        const installerOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: false });
-
-        assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            true,
-            'the unresolved-dependency install holds both prunes',
-        );
-        const recordedSkills = new Set(readManifest(sandbox.manifestPath).skills);
-        assert.equal(
-            recordedSkills.has(DEPENDENCY_SUPPLIED_SKILL_DIRECTORY),
-            true,
-            'the name a later pruning install needs to spot the retired skill stays on the record',
-        );
-        assert.equal(
-            recordedSkills.has(SHIPPED_SKILL_DIRECTORY),
-            true,
-            'the held run still records the skills it installed itself',
+            'the shipped autoconverge overwrites the stale seeded copy',
         );
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
@@ -856,43 +680,38 @@ test('a scoped core install ships the canonical review guide skills', () => {
     }
 });
 
-test('the prune skip is scoped: once the dependency resolves a later full install prunes normally', () => {
+test('a scoped core install leaves retired skills in place; a later full install prunes them', () => {
     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',
-        );
+        runInstaller(sandbox.homeDirectory, ['--only', 'core']);
         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`,
+                `retired skill ${retiredSkill} should survive a scoped install`,
             );
         }
 
-        const resolvedOutput = runInstaller(sandbox.homeDirectory, [], { dependencyResolvable: true });
+        const fullOutput = runInstaller(sandbox.homeDirectory, []);
         assert.equal(
-            resolvedOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
+            fullOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
             false,
-            'the resolved-dependency install runs the prune, proving the skip is not a permanent disable',
+            'the full install runs the prune',
         );
         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`,
+                `retired skill ${retiredSkill} should be pruned on the full install`,
             );
             assert.equal(
                 prunedSkillBackupContains(sandbox.claudeDirectory, retiredSkill),
                 true,
-                `retired skill ${retiredSkill} should be moved to the prune backup on the resolved install`,
+                `retired skill ${retiredSkill} should be moved to the prune backup`,
             );
         }
     } finally {

package/bin/install.test.mjs

@@ -214,6 +214,12 @@ test('CORE_SKILLS ships issue-tracker so the core group installs the skill the S
 });
 
 
+test('CORE_SKILLS ships ELI5 as the leaf presentation skill', () => {
+    assert.ok(CORE_SKILLS.includes('eli5'), 'eli5 must be in CORE_SKILLS');
+    assert.equal(INSTALL_GROUPS.core.skills.includes('eli5'), true);
+});
+
+
 test('EVER_SHIPPED_SKILL_NAMES retains imagegen so reinstall prunes the retired skill', () => {
     assert.ok(
         EVER_SHIPPED_SKILL_NAMES.has('imagegen'),
@@ -980,7 +986,6 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/claude_md_orphan_file_blocker.py', timeout: 10 },
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/pytest_testpaths_orphan_blocker.py', timeout: 10 },
                     { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/open_questions_in_plans_blocker.py', timeout: 10 },
-                    { type: 'command', command: 'py -3 C:/Users/x/.claude/hooks/blocking/plain_language_blocker.py', timeout: 10 },
                 ],
             },
         ],
@@ -988,10 +993,9 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-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);
+test('FOLDED_HOOK_RELATIVE_PATHS contains all 14 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 15);
     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'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/md_to_html_blocker.py'));
@@ -1014,7 +1018,6 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
         'blocking/env_var_table_code_drift_blocker.py',
         'blocking/pytest_testpaths_orphan_blocker.py',
         'blocking/open_questions_in_plans_blocker.py',
-        'blocking/plain_language_blocker.py',
     ];
     const retiredHooks = [
         'blocking/md_to_html_blocker.py',

package/bin/resolve-install-root.mjs

@@ -20,6 +20,9 @@ import {
     CURSOR_RULES_DIRECTORY_NAME,
     MANAGED_SKILLS_DIRECTORY_NAME,
     MANAGED_AGENTS_DIRECTORY_NAME,
+    MANAGED_HOOKS_DIRECTORY_NAME,
+    MANAGED_SCRIPTS_DIRECTORY_NAME,
+    CODEX_HOOKS_DIRECTORY_NAME,
 } from './install-constants.mjs';
 
 export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
@@ -52,6 +55,11 @@ export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
  *   agentsInstallDirectory: string,
  *   skillsLookupDirectory: string,
  *   agentsLookupDirectory: string,
+ *   hooksInstallDirectory: string,
+ *   scriptsInstallDirectory: string,
+ *   hooksLookupDirectory: string,
+ *   scriptsLookupDirectory: string,
+ *   codexHooksInstallDirectory: string,
  * }} InstallRootResolution
  */
 
@@ -127,6 +135,9 @@ export function resolveInstallRoot(options = {}) {
     const codexRulesInstallDirectory = resolve(
         join(codexHomeDirectory, CODEX_RULES_DIRECTORY_NAME),
     );
+    const codexHooksInstallDirectory = resolve(
+        join(codexHomeDirectory, CODEX_HOOKS_DIRECTORY_NAME),
+    );
     const cursorInstallDirectory = resolve(
         join(homeDirectory, DEFAULT_CURSOR_DIRECTORY_NAME),
     );
@@ -136,8 +147,12 @@ export function resolveInstallRoot(options = {}) {
     const agentsHome = resolveAgentsHome(managedRoot);
     const skillsInstallDirectory = join(agentsHome, MANAGED_SKILLS_DIRECTORY_NAME);
     const agentsInstallDirectory = join(agentsHome, MANAGED_AGENTS_DIRECTORY_NAME);
+    const hooksInstallDirectory = join(agentsHome, MANAGED_HOOKS_DIRECTORY_NAME);
+    const scriptsInstallDirectory = join(agentsHome, MANAGED_SCRIPTS_DIRECTORY_NAME);
     const skillsLookupDirectory = join(managedRoot, MANAGED_SKILLS_DIRECTORY_NAME);
     const agentsLookupDirectory = join(managedRoot, MANAGED_AGENTS_DIRECTORY_NAME);
+    const hooksLookupDirectory = join(managedRoot, MANAGED_HOOKS_DIRECTORY_NAME);
+    const scriptsLookupDirectory = join(managedRoot, MANAGED_SCRIPTS_DIRECTORY_NAME);
     return {
         managedRoot,
         source,
@@ -147,6 +162,7 @@ export function resolveInstallRoot(options = {}) {
         allDeclaredExternalPaths: [mypyIniInstallPath],
         allDeclaredExternalDirectories: [
             codexRulesInstallDirectory,
+            codexHooksInstallDirectory,
             cursorInstallDirectory,
             agentsHome,
         ],
@@ -158,6 +174,11 @@ export function resolveInstallRoot(options = {}) {
         agentsInstallDirectory,
         skillsLookupDirectory,
         agentsLookupDirectory,
+        hooksInstallDirectory,
+        scriptsInstallDirectory,
+        hooksLookupDirectory,
+        scriptsLookupDirectory,
+        codexHooksInstallDirectory,
     };
 }
 

package/bin/resolve-package-managed-directory.mjs

@@ -1,10 +1,10 @@
 /**
  * Resolve a managed content directory in a package source tree.
  *
- * This package keeps skills and agents under `.agents/<name>/`. A dependency
+ * This package keeps managed trees under `.agents/<name>/`. A dependency
  * package may still keep those trees at `<package-root>/<name>/`. Callers pass
- * the package root and the managed directory name (`skills` or `agents`); this
- * helper returns the directory that exists.
+ * the package root and the managed directory name; this helper returns the
+ * directory that exists.
  */
 
 import { existsSync } from 'node:fs';
@@ -13,7 +13,7 @@ import { PACKAGE_AGENTS_HOME_DIRECTORY_NAME } from './install-constants.mjs';
 
 /**
  * @param {string} sourceRoot Package root that may hold `.agents/<name>` or `<name>`.
- * @param {string} directoryName Managed directory name (`skills` or `agents`).
+ * @param {string} directoryName Managed directory name.
  * @returns {string} Absolute source directory to copy from.
  */
 export function resolvePackageManagedDirectory(sourceRoot, directoryName) {

package/commands/AGENTS.md

@@ -2,6 +2,8 @@
 
 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 bodies use `rules/asd-ste100-language.md` for user-facing word choice, sentence style, tone, punctuation, and prose form. Each command keeps its workflow contract.
+
 ## Command files
 
 | File | Command | What it does |

package/commands/sr-loop.md

@@ -7,6 +7,9 @@ Run the converging cleanup loop on the target: `$ARGUMENTS` (blank means the
 current branch's diff). Each phase invokes an existing skill with the Skill
 tool and repeats it until a pass returns zero new findings.
 
+Use `rules/asd-ste100-language.md` for user-facing wording. Keep the loop's
+cleanup, verification, commit, push, and finish-report fields.
+
 ## Phase A — loop /simplify
 
 1. Invoke the `simplify` skill on the target (the same review the user gets

package/docs/references/prose-style-enforcement.md

@@ -1,6 +1,6 @@
 # Prose-style enforcement
 
-Opinionated prose gates (heavy-word swaps, hedging, historical state phrasing, intent-only endings, hook prose-detector consistency) are **off by default**.
+Opinionated prose gates (hedging, historical state phrasing, intent-only endings, hook prose-detector consistency) are **off by default**.
 
 ## Opt-in
 
@@ -10,16 +10,12 @@ The flag is `PROSE_STYLE_ENFORCEMENT_ENABLED` in `hooks/blocking/config/prose_st
 
 ## Always on
 
-Structural AskUserQuestion lean-block validation in `plain_language_blocker` (chat detail, length caps on question blocks) stays active regardless of the flag. Code-rules and security blockers are out of scope for this switch.
+Structural AskUserQuestion lean-block validation in `ask_user_question_shape_blocker` (chat detail, length caps on question blocks) stays active regardless of the flag. Apply `rules/asd-ste100-language.md` for user-facing word choice and sentence style. Code-rules and security blockers are out of scope for this switch.
 
 ## Advisory precision measurement (OP-07B)
 
-When the flag is off, heavy-word and hedging hits still emit privacy-safe advisory candidates to `~/.claude/logs/prose-matcher-advisory.jsonl` (matcher id, surface, hashed context fingerprint, optional label). Classification (`keep` / `narrow` / `drop` / `advisory`) uses a labeled sample floor of 30 and precision floors 0.7 / 0.4. Matchers below the floor stay advisory. No matcher becomes hard-blocking from historical labels alone. See `hooks/observability/prose_matcher_advisory.py`.
+When the flag is off, hedging hits still emit privacy-safe advisory candidates to `~/.claude/logs/prose-matcher-advisory.jsonl` (matcher id, surface, hashed context fingerprint, optional label). Classification (`keep` / `narrow` / `drop` / `advisory`) uses a labeled sample floor of 30 and precision floors 0.7 / 0.4. Matchers below the floor stay advisory. See `hooks/observability/prose_matcher_advisory.py`.
 
 ## Explicit uncertainty (OP-07C)
 
 With enforcement on, a hedge word in a sentence that also labels the claim (`unverified`, `I don't know`, `no source for this claim`, …) passes. A bare hedge in a different sentence still blocks. Detail: `rules/hedging-claims.md`.
-
-## Plain-language advisory (OP-07D)
-
-Heavy-word matches never hard-deny a Write/Edit or AskUserQuestion. With enforcement on, the hook allows the call and returns a `systemMessage` that names everyday swaps for both AskUserQuestion and `.md` writes. Lean-block structure denials stay hard. Detail: `rules/plain-language.md`.

package/hooks/AGENTS.md

@@ -9,9 +9,6 @@ Python hook scripts wired into Claude Code's lifecycle via `settings.json`. Each
 | `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) |

package/hooks/blocking/AGENTS.md

@@ -74,7 +74,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
 | `docstring_rule_gate_count_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A stale spelled-out gate-validator count in `docstring-prose-matches-implementation.md` — the "N more gate validators" / "M gated slices" count drifting from the `check_docstring_*` validators the prose names |
 | `duplicate_rmtree_helper_blocker.py` | PreToolUse (Write/Edit) | A local re-definition of the Windows-safe rmtree helper trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`) in place of importing a shared helper |
-| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 6 bullet lines, more than 2 list lines over 20 words each, or multi-line instructions with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged. |
 | `env_var_table_code_drift_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A markdown env-var summary table row attributing an environment variable to a code file whose source never references that variable name |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
 | `fable_spawn_gate.py` | PreToolUse (Agent/Task) | An `Agent` or `Task` spawn whose prompt carries no `FABLE-SPAWN-AUTHORIZED` token and whose model field reads `fable` in any letter case — the bare alias, or a delimiter segment of a full model id, so `claude-fable-5` is denied too |
@@ -92,7 +91,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Entry hook — 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; resolves the staged-commit repository from the command it gates (via `pii_prevention_blocker_parts`), not the session working directory |
 | `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
 | `piped_pytest_blocker.py` | PreToolUse (Bash) | A pytest run whose output feeds a pipe, where the pipeline reports the exit code of the command on the right |
-| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off); AskUserQuestion lean-block structure stays always on |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |

package/hooks/blocking/ask_user_question_shape_blocker.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that enforces AskUserQuestion field shape."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.ask_user_question_shape import (  # noqa: E402
+    analyze_ask_user_question_shape,
+)
+from hooks_constants.ask_user_question_shape_constants import (  # noqa: E402
+    ASK_USER_QUESTION_TOOL_NAME,
+    LEAN_QUESTION_BLOCK_GUIDANCE,
+    LEAN_QUESTION_BLOCK_PREFIX,
+    LEAN_QUESTION_VIOLATION_SEPARATOR,
+    USER_FACING_LEAN_QUESTION_NOTICE,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+
+
+def build_lean_block_reason(all_violations: Sequence[str]) -> str:
+    """Build a deny reason that names each field-shape violation."""
+    violation_list = LEAN_QUESTION_VIOLATION_SEPARATOR.join(all_violations)
+    return f"{LEAN_QUESTION_BLOCK_PREFIX}{violation_list}. {LEAN_QUESTION_BLOCK_GUIDANCE}"
+
+
+def evaluate(payload_by_key: Mapping[str, object]) -> str | None:
+    """Return a deny reason when an AskUserQuestion payload breaks field shape."""
+    tool_name = payload_by_key.get("tool_name", "")
+    tool_input = payload_by_key.get("tool_input", {})
+    if tool_name != ASK_USER_QUESTION_TOOL_NAME:
+        return None
+    if not isinstance(tool_input, Mapping):
+        return None
+    shape_result = analyze_ask_user_question_shape(tool_input)
+    if shape_result.is_lean:
+        return None
+    return build_lean_block_reason(shape_result.all_violations)
+
+
+def build_deny_payload(deny_reason: str) -> dict[str, object]:
+    """Build the standard PreToolUse deny payload for a shape violation."""
+    log_hook_block(
+        calling_hook_name="ask_user_question_shape_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        },
+        "systemMessage": USER_FACING_LEAN_QUESTION_NOTICE,
+        "suppressOutput": True,
+    }
+
+
+def main() -> None:
+    """Read one PreToolUse payload and deny malformed question shape."""
+    try:
+        payload_by_key = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if not isinstance(payload_by_key, dict):
+        sys.exit(0)
+    deny_reason = evaluate(payload_by_key)
+    if deny_reason is None:
+        sys.exit(0)
+    sys.stdout.write(json.dumps(build_deny_payload(deny_reason)))
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()