claude-dev-env 2.9.0 → 2.10.0

package/bin/resolve-install-root.mjs

@@ -0,0 +1,181 @@
+/**
+ * Pure install-root resolver for the claude-dev-env installer.
+ *
+ * Precedence (highest first):
+ *   1. explicitTarget — CLI --target or a caller-supplied absolute path
+ *   2. CLAUDE_CONFIG_DIR from the environment (profile isolation root)
+ *   3. join(homeDirectory, '.claude') — main-profile default
+ *
+ * CLAUDE_HOME is never honored as a profile root.
+ */
+
+import { homedir } from 'node:os';
+import { join, normalize, resolve, sep } from 'node:path';
+import { MYPY_INI_FILE_NAME } from './install-constants.mjs';
+
+export const CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE = 'CLAUDE_CONFIG_DIR';
+export const DEFAULT_CLAUDE_DIRECTORY_NAME = '.claude';
+export const MANIFEST_FILE_NAME = '.claude-dev-env-manifest.json';
+
+/**
+ * @typedef {{
+ *   explicitTarget?: string | null,
+ *   environment?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   homeDirectory?: string,
+ * }} ResolveInstallRootOptions
+ */
+
+/**
+ * @typedef {{
+ *   managedRoot: string,
+ *   source: 'explicit-target' | 'claude-config-dir' | 'default-home',
+ *   homeDirectory: string,
+ *   manifestFilePath: string,
+ *   mypyIniInstallPath: string,
+ *   allDeclaredExternalPaths: string[],
+ * }} InstallRootResolution
+ */
+
+/**
+ * Resolve the managed install root and declared external destinations.
+ *
+ * @param {ResolveInstallRootOptions} [options]
+ * @returns {InstallRootResolution}
+ */
+export function resolveInstallRoot(options = {}) {
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const environment = options.environment ?? process.env;
+    const explicitTarget = normalizeOptionalPath(options.explicitTarget);
+
+    /** @type {InstallRootResolution['source']} */
+    let source;
+    /** @type {string} */
+    let managedRoot;
+
+    if (explicitTarget) {
+        managedRoot = explicitTarget;
+        source = 'explicit-target';
+    } else {
+        const configDir = normalizeOptionalPath(
+            environment[CLAUDE_CONFIG_DIR_ENVIRONMENT_VARIABLE],
+        );
+        if (configDir) {
+            managedRoot = configDir;
+            source = 'claude-config-dir';
+        } else {
+            managedRoot = resolve(join(homeDirectory, DEFAULT_CLAUDE_DIRECTORY_NAME));
+            source = 'default-home';
+        }
+    }
+
+    const mypyIniInstallPath = resolve(join(homeDirectory, MYPY_INI_FILE_NAME));
+    return {
+        managedRoot,
+        source,
+        homeDirectory: resolve(homeDirectory),
+        manifestFilePath: join(managedRoot, MANIFEST_FILE_NAME),
+        mypyIniInstallPath,
+        allDeclaredExternalPaths: [mypyIniInstallPath],
+    };
+}
+
+/**
+ * True when candidatePath is the managed root or a descendant of it.
+ * Requires a separator boundary so `.claude-extra` is not inside `.claude`.
+ *
+ * @param {string} candidatePath
+ * @param {string} managedRoot
+ * @returns {boolean}
+ */
+export function isPathWithinManagedRoot(candidatePath, managedRoot) {
+    if (!candidatePath || !managedRoot) {
+        return false;
+    }
+    const normalizedCandidate = normalizePathForComparison(candidatePath);
+    const normalizedRoot = normalizePathForComparison(managedRoot);
+    if (normalizedCandidate === normalizedRoot) {
+        return true;
+    }
+    const rootWithSeparator = normalizedRoot.endsWith('/')
+        ? normalizedRoot
+        : `${normalizedRoot}/`;
+    return normalizedCandidate.startsWith(rootWithSeparator);
+}
+
+/**
+ * True when a write destination is allowed: inside the managed root or on
+ * the declared external allowlist (today: ~/.mypy.ini under the home dir).
+ *
+ * @param {string} candidatePath
+ * @param {InstallRootResolution} resolution
+ * @returns {boolean}
+ */
+export function isAllowedInstallDestination(candidatePath, resolution) {
+    if (isPathWithinManagedRoot(candidatePath, resolution.managedRoot)) {
+        return true;
+    }
+    const normalizedCandidate = normalizePathForComparison(candidatePath);
+    return resolution.allDeclaredExternalPaths.some(
+        (eachExternalPath) => normalizePathForComparison(eachExternalPath) === normalizedCandidate,
+    );
+}
+
+/**
+ * Parse an explicit --target value from argv tokens.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+export function parseExplicitTargetFromArgv(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--target') {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--target requires a path argument');
+            }
+            return value;
+        }
+        if (token.startsWith('--target=')) {
+            const value = token.slice('--target='.length);
+            if (!value) {
+                throw new Error('--target requires a path argument');
+            }
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string | null | undefined} maybePath
+ * @returns {string | null}
+ */
+function normalizeOptionalPath(maybePath) {
+    if (typeof maybePath !== 'string') {
+        return null;
+    }
+    const trimmed = maybePath.trim();
+    if (!trimmed) {
+        return null;
+    }
+    return resolve(trimmed);
+}
+
+/**
+ * Compare-key for a filesystem path: resolve, forward-slash, case-fold on win32.
+ *
+ * @param {string} filesystemPath
+ * @returns {string}
+ */
+export function normalizePathForComparison(filesystemPath) {
+    const resolved = resolve(normalize(filesystemPath));
+    let withForwardSlashes = resolved.split(sep).join('/');
+    if (process.platform === 'win32') {
+        withForwardSlashes = withForwardSlashes.toLowerCase();
+    }
+    if (withForwardSlashes.length > 1 && withForwardSlashes.endsWith('/')) {
+        withForwardSlashes = withForwardSlashes.slice(0, -1);
+    }
+    return withForwardSlashes;
+}

package/bin/select-install-targets.mjs

@@ -0,0 +1,401 @@
+/**
+ * Pure install-target selection for single-profile and selected multi-profile runs.
+ *
+ * Selection finishes before any filesystem mutation. The caller injects the
+ * profiles root and the profile-id → directoryName map so tests need no live
+ * env or disk fixtures.
+ */
+
+import { join, resolve, isAbsolute, normalize } from 'node:path';
+import {
+    resolveInstallRoot,
+    parseExplicitTargetFromArgv,
+    normalizePathForComparison,
+} from './resolve-install-root.mjs';
+
+export const MAIN_DEFAULT_TARGET_IDENTITY = 'main';
+export const TARGET_IDENTITY_FLAG = '--target-identity';
+export const PROFILE_FLAG = '--profile';
+export const PROFILES_FLAG = '--profiles';
+export const DEFAULT_PROFILES_ROOT_DIRECTORY_NAME = '.claude-profiles';
+export const PROFILES_ROOT_ENVIRONMENT_VARIABLE = 'LLM_SETTINGS_PROFILES_ROOT';
+
+/**
+ * @typedef {{
+ *   mode: 'main-default' | 'explicit-path' | 'profiles' | 'child-identity',
+ *   allProfileIds: string[],
+ *   explicitTarget: string | null,
+ *   targetIdentity: string | null,
+ * }} InstallTargetSelection
+ */
+
+/**
+ * @typedef {{
+ *   targetIdentity: string,
+ *   managedRoot: string,
+ *   source: string,
+ *   profileId: string | null,
+ * }} ResolvedInstallTarget
+ */
+
+/**
+ * Parse target-selection flags from argv. Does not resolve paths.
+ *
+ * Rejects ambiguous combinations (path target + profile), empty profile lists,
+ * and a child hop that still carries profile flags.
+ *
+ * @param {string[]} argv
+ * @returns {InstallTargetSelection}
+ */
+export function parseInstallTargetSelectionFromArgv(argv) {
+    const explicitTarget = parseExplicitTargetFromArgv(argv);
+    const targetIdentity = parseTargetIdentityFromArgv(argv);
+    const allProfileIds = parseProfileIdsFromArgv(argv);
+    const hasProfileFlags = allProfileIds.length > 0
+        || argvIncludesFlag(argv, PROFILE_FLAG)
+        || argvIncludesFlag(argv, PROFILES_FLAG);
+
+    if (targetIdentity && hasProfileFlags) {
+        throw new Error(
+            'child install hop rejects --profile/--profiles when --target-identity is set',
+        );
+    }
+    if (explicitTarget && hasProfileFlags) {
+        throw new Error(
+            'ambiguous targets: use either --target <path> or --profile/--profiles, not both',
+        );
+    }
+    if (hasProfileFlags && allProfileIds.length === 0) {
+        throw new Error('--profile/--profiles requires at least one profile id');
+    }
+    if (allProfileIds.length > 0) {
+        const allDuplicates = findDuplicateStrings(allProfileIds);
+        if (allDuplicates.length > 0) {
+            throw new Error(`duplicate profile id(s): ${allDuplicates.join(', ')}`);
+        }
+        return {
+            mode: 'profiles',
+            allProfileIds,
+            explicitTarget: null,
+            targetIdentity: null,
+        };
+    }
+    if (targetIdentity) {
+        return {
+            mode: 'child-identity',
+            allProfileIds: [],
+            explicitTarget,
+            targetIdentity,
+        };
+    }
+    if (explicitTarget) {
+        return {
+            mode: 'explicit-path',
+            allProfileIds: [],
+            explicitTarget,
+            targetIdentity: null,
+        };
+    }
+    return {
+        mode: 'main-default',
+        allProfileIds: [],
+        explicitTarget: null,
+        targetIdentity: null,
+    };
+}
+
+/**
+ * Resolve the ordered list of install targets from a parsed selection.
+ *
+ * Dedupes on the resolved managed root path (case-insensitive on Windows) so
+ * `--target` and a profile that names the same directory cannot both run.
+ * Sanitizes each profile directoryName: absolute paths and `..` segments fail.
+ *
+ * @param {InstallTargetSelection} selection
+ * @param {{
+ *   homeDirectory: string,
+ *   environment?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   profilesRoot?: string | null,
+ *   directoryNameByProfileId?: Record<string, string>,
+ * }} options
+ * @returns {ResolvedInstallTarget[]}
+ */
+export function resolveInstallTargets(selection, options) {
+    const environment = options.environment ?? {};
+    const homeDirectory = options.homeDirectory;
+    const directoryNameByProfileId = options.directoryNameByProfileId ?? {};
+
+    if (selection.mode === 'profiles') {
+        const profilesRoot = resolveProfilesRootDirectory({
+            homeDirectory,
+            environment,
+            profilesRoot: options.profilesRoot,
+        });
+        /** @type {ResolvedInstallTarget[]} */
+        const allTargets = [];
+        for (const eachProfileId of selection.allProfileIds) {
+            const directoryName = directoryNameByProfileId[eachProfileId];
+            if (typeof directoryName !== 'string' || !directoryName.trim()) {
+                throw new Error(`unknown profile id: ${eachProfileId}`);
+            }
+            const safeDirectoryName = assertSafeProfileDirectoryName(directoryName);
+            const managedRoot = resolve(join(profilesRoot, safeDirectoryName));
+            allTargets.push({
+                targetIdentity: eachProfileId,
+                managedRoot,
+                source: 'selected-profile',
+                profileId: eachProfileId,
+            });
+        }
+        return dedupeTargetsByManagedRoot(allTargets);
+    }
+
+    const explicitTarget = selection.mode === 'main-default' ? null : selection.explicitTarget;
+    const resolution = resolveInstallRoot({
+        homeDirectory,
+        environment,
+        explicitTarget,
+    });
+    const isChildIdentity = selection.mode === 'child-identity';
+    return [{
+        targetIdentity: isChildIdentity
+            ? (selection.targetIdentity ?? MAIN_DEFAULT_TARGET_IDENTITY)
+            : MAIN_DEFAULT_TARGET_IDENTITY,
+        managedRoot: resolution.managedRoot,
+        source: resolution.source,
+        profileId: isChildIdentity ? selection.targetIdentity : null,
+    }];
+}
+
+/**
+ * Build the per-target ownership manifest record.
+ *
+ * @param {{
+ *   packageName: string,
+ *   packageVersion: string,
+ *   targetIdentity: string,
+ *   managedRoot: string,
+ *   files: string[],
+ *   skills?: string[] | null,
+ *   installedAt?: string,
+ * }} parameters
+ * @returns {Record<string, unknown>}
+ */
+export function buildTargetManifestRecord(parameters) {
+    /** @type {Record<string, unknown>} */
+    const manifest = {
+        package: parameters.packageName,
+        version: parameters.packageVersion,
+        installedAt: parameters.installedAt ?? new Date().toISOString(),
+        targetIdentity: parameters.targetIdentity,
+        managedRoot: parameters.managedRoot,
+        files: parameters.files,
+    };
+    if (parameters.skills) {
+        manifest.skills = parameters.skills;
+    }
+    return manifest;
+}
+
+/**
+ * Strip target-selection flags so group parsing sees only install flags.
+ *
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+export function stripTargetSelectionFlagsFromArgv(argv) {
+    /** @type {string[]} */
+    const remaining = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === PROFILE_FLAG || token === PROFILES_FLAG || token === TARGET_IDENTITY_FLAG) {
+            const value = argv[index + 1];
+            if (value && !value.startsWith('--')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (
+            token.startsWith(`${PROFILE_FLAG}=`)
+            || token.startsWith(`${PROFILES_FLAG}=`)
+            || token.startsWith(`${TARGET_IDENTITY_FLAG}=`)
+        ) {
+            continue;
+        }
+        if (token === '--target') {
+            const value = argv[index + 1];
+            if (value && !value.startsWith('--')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (token.startsWith('--target=')) {
+            continue;
+        }
+        remaining.push(token);
+    }
+    return remaining;
+}
+
+/**
+ * @param {{
+ *   homeDirectory: string,
+ *   environment?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ *   profilesRoot?: string | null,
+ * }} options
+ * @returns {string}
+ */
+export function resolveProfilesRootDirectory(options) {
+    if (typeof options.profilesRoot === 'string' && options.profilesRoot.trim()) {
+        return resolve(options.profilesRoot);
+    }
+    const environment = options.environment ?? {};
+    const fromEnvironment = environment[PROFILES_ROOT_ENVIRONMENT_VARIABLE];
+    if (typeof fromEnvironment === 'string' && fromEnvironment.trim()) {
+        return resolve(fromEnvironment.trim());
+    }
+    return resolve(join(options.homeDirectory, DEFAULT_PROFILES_ROOT_DIRECTORY_NAME));
+}
+
+/**
+ * Reject absolute and parent-hop directoryName values on every host platform.
+ *
+ * Host `isAbsolute` plus Windows drive and UNC spellings so a Linux CI host
+ * still rejects a profile map that smuggles an absolute Windows path.
+ *
+ * @param {string} directoryName
+ * @returns {string}
+ */
+export function assertSafeProfileDirectoryName(directoryName) {
+    const trimmed = directoryName.trim();
+    if (!trimmed) {
+        throw new Error('profile directoryName must be a non-empty relative name');
+    }
+    const hasWindowsDriveAbsolute = /^[A-Za-z]:[\\/]/.test(trimmed);
+    const hasWindowsUncAbsolute = trimmed.startsWith('\\\\') || trimmed.startsWith('//');
+    if (isAbsolute(trimmed) || hasWindowsDriveAbsolute || hasWindowsUncAbsolute) {
+        throw new Error(`profile directoryName must be relative, got absolute: ${trimmed}`);
+    }
+    const allSegments = normalize(trimmed).split(/[/\\]/).filter(Boolean);
+    if (allSegments.some((eachSegment) => eachSegment === '..')) {
+        throw new Error(`profile directoryName rejects parent segments: ${trimmed}`);
+    }
+    return trimmed;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+function parseProfileIdsFromArgv(argv) {
+    /** @type {string[]} */
+    const allProfileIds = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === PROFILE_FLAG || token === PROFILES_FLAG) {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error(`${token} requires a comma-separated profile id list`);
+            }
+            allProfileIds.push(...splitProfileIdList(value));
+            index += 1;
+            continue;
+        }
+        if (token.startsWith(`${PROFILE_FLAG}=`) || token.startsWith(`${PROFILES_FLAG}=`)) {
+            const prefix = token.startsWith(`${PROFILE_FLAG}=`)
+                ? `${PROFILE_FLAG}=`
+                : `${PROFILES_FLAG}=`;
+            const value = token.slice(prefix.length);
+            if (!value) {
+                throw new Error(`${prefix.slice(0, -1)} requires a comma-separated profile id list`);
+            }
+            allProfileIds.push(...splitProfileIdList(value));
+        }
+    }
+    return allProfileIds;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+function parseTargetIdentityFromArgv(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === TARGET_IDENTITY_FLAG) {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error(`${TARGET_IDENTITY_FLAG} requires an identity argument`);
+            }
+            return value;
+        }
+        if (token.startsWith(`${TARGET_IDENTITY_FLAG}=`)) {
+            const value = token.slice(`${TARGET_IDENTITY_FLAG}=`.length);
+            if (!value) {
+                throw new Error(`${TARGET_IDENTITY_FLAG} requires an identity argument`);
+            }
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string} rawList
+ * @returns {string[]}
+ */
+function splitProfileIdList(rawList) {
+    return rawList
+        .split(',')
+        .map((eachId) => eachId.trim())
+        .filter((eachId) => eachId.length > 0);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {string} flagName
+ * @returns {boolean}
+ */
+function argvIncludesFlag(argv, flagName) {
+    return argv.some(
+        (eachToken) => eachToken === flagName || eachToken.startsWith(`${flagName}=`),
+    );
+}
+
+/**
+ * @param {string[]} allValues
+ * @returns {string[]}
+ */
+function findDuplicateStrings(allValues) {
+    const seen = new Set();
+    const allDuplicates = new Set();
+    for (const eachValue of allValues) {
+        if (seen.has(eachValue)) {
+            allDuplicates.add(eachValue);
+        }
+        seen.add(eachValue);
+    }
+    return [...allDuplicates];
+}
+
+/**
+ * @param {ResolvedInstallTarget[]} allTargets
+ * @returns {ResolvedInstallTarget[]}
+ */
+function dedupeTargetsByManagedRoot(allTargets) {
+    const seenRootByKey = new Map();
+    /** @type {ResolvedInstallTarget[]} */
+    const uniqueTargets = [];
+    for (const eachTarget of allTargets) {
+        const rootKey = normalizePathForComparison(eachTarget.managedRoot);
+        if (seenRootByKey.has(rootKey)) {
+            const priorIdentity = seenRootByKey.get(rootKey);
+            throw new Error(
+                `duplicate managed root for targets ${priorIdentity} and ${eachTarget.targetIdentity}: ${eachTarget.managedRoot}`,
+            );
+        }
+        seenRootByKey.set(rootKey, eachTarget.targetIdentity);
+        uniqueTargets.push(eachTarget);
+    }
+    return uniqueTargets;
+}

package/commands/CLAUDE.md

@@ -11,12 +11,10 @@ Slash-command definitions installed into `~/.claude/commands/` by `bin/install.m
 | `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 |
-| `initialize.md` | `/initialize` | Bootstraps a new project with standard Claude Code config |
 | `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 |
-| `stubcheck.md` | `/stubcheck` | Finds stub bodies (`pass`/`...`/`raise NotImplementedError`) in the diff |
 | `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
 
 ## Format

package/docs/references/CLAUDE.md

@@ -8,6 +8,7 @@ Pointer documents to external sources, standard terminology, and internal tool o
 |---|---|
 | `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 how it pairs with `advisor()` |
 

package/docs/references/advisor-tool.md

@@ -34,7 +34,7 @@ Your first write, edit, or state-changing shell call on a task must be preceded
 
 Give the advice serious weight. If a step fails empirically, or primary-source evidence contradicts a claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it is evidence the test does not check what the advice is checking.
 
-If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" A reconcile call is cheaper than the wrong branch.
+If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw the evidence but may have underweighted it; a reconcile call is cheaper than the wrong branch.
 
 ## Brevity cue
 

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

@@ -0,0 +1,25 @@
+# Prose-style enforcement
+
+Opinionated prose gates (heavy-word swaps, hedging, historical state phrasing, intent-only endings, hook prose-detector consistency) are **off by default**.
+
+## Opt-in
+
+Set `CLAUDE_PROSE_STYLE_ENFORCEMENT` to `1`, `true`, `yes`, or `on` (case and spaces ignored). Any other value, and an unset variable, leave those gates off.
+
+The flag is `PROSE_STYLE_ENFORCEMENT_ENABLED` in `hooks/blocking/config/prose_style_enforcement_constants.py`.
+
+## 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.
+
+## 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`.
+
+## 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/blocking/CLAUDE.md

@@ -82,16 +82,16 @@ 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 120 reader-visible words, more than 6 bullet lines, more than 2 lines carrying over 20 words each, or instruction lines telling the user to act 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, replies under 60 words always pass, and a reply opening with `Long form:` opts out entirely |
+| `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 |
 | `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
 | `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
 | `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
-| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`) |
-| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
-| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
+| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`); armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
 | `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 |
@@ -100,7 +100,7 @@ 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 |
+| `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 |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
 | `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
@@ -113,7 +113,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
 | `shell_substitution_blocker.py` | PreToolUse (Bash) | A command carrying `$(...)`, a live backtick, or `<(...)`/`>(...)` process substitution, which the allowlist matcher cannot descend into |
 | `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
-| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |
+| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
 | `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
 | `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
 | `unscoped_search_blocker.py` | PreToolUse (Bash/PowerShell) | A `find` or recursive listing that walks from the filesystem root, a drive root, bare home, or a network share root |