claude-git-hooks 2.61.2 → 2.67.3

package/lib/commands/bump-version.js

@@ -24,8 +24,7 @@ import {
     discoverVersionFiles,
     incrementVersion,
     modifySuffix,
-    updateVersionFiles,
-    validateVersionFormat
+    updateVersionFiles
 } from '../utils/version-manager.js';
 import { createTag, pushTags, tagExists, formatTagName } from '../utils/git-tag-manager.js';
 import {
@@ -48,11 +47,10 @@ import {
     showError,
     showWarning,
     promptConfirmation,
-    promptMenu,
-    promptToggleList,
-    promptEditField
+    promptToggleList
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { colors, error, checkGitRepo } from './helpers.js';
 import {
     CONSOLE_WARNING_TEMPLATE,
@@ -209,7 +207,9 @@ function displayDiscoveryTable(discovery) {
     );
     console.log('');
 
-    if (discovery.files.length === 0) {
+    const visibleFiles = discovery.files.filter((f) => f.selected);
+
+    if (visibleFiles.length === 0) {
         console.log('  No version files found.');
         console.log('');
         return;
@@ -221,8 +221,8 @@ function displayDiscoveryTable(discovery) {
     );
     console.log(`  ${'-'.repeat(3)} ${'-'.repeat(35)} ${'-'.repeat(15)} ${'-'.repeat(15)}`);
 
-    // Table rows
-    discovery.files.forEach((file, index) => {
+    // Table rows (only semver files)
+    visibleFiles.forEach((file, index) => {
         const num = `${index + 1}`.padEnd(3);
         const filePath = file.relativePath.padEnd(35);
         const fileType = file.projectLabel.padEnd(15);
@@ -293,70 +293,20 @@ function showDryRunPreview(info) {
  */
 async function promptFileSelection(discovery) {
     console.log('');
-    showWarning('Version mismatch detected or interactive mode enabled');
-    console.log('');
-
-    const options = [
-        { key: 'a', label: 'Update all files' },
-        { key: 's', label: 'Select which files to update' },
-        { key: 'e', label: 'Edit version per file (advanced)' },
-        { key: 'c', label: 'Cancel' }
-    ];
-
-    const choice = await promptMenu('Choose action:', options, 'a');
-
-    if (choice === 'c') {
-        showInfo('Version bump cancelled');
-        process.exit(0);
-    }
-
-    if (choice === 'a') {
-        // All files selected
-        return discovery.files;
-    }
 
-    if (choice === 's') {
-        // Toggle list selection
-        const items = discovery.files.map((file, index) => ({
-            key: `${index}`,
-            label: `${file.relativePath} (${file.projectLabel}) - ${file.version || 'N/A'}`,
-            selected: file.selected
-        }));
-
-        const selectedKeys = await promptToggleList(
-            'Select files to update (type number to toggle, Enter to confirm):',
-            items
-        );
-
-        // Filter files by selected keys
-        return discovery.files.filter((_, index) => selectedKeys.includes(`${index}`));
-    }
-
-    if (choice === 'e') {
-        // Per-file version editing
-        showInfo('Enter target version for each file (press Enter to keep calculated version)');
-        console.log('');
-
-        for (const file of discovery.files) {
-            const input = await promptEditField(
-                `${file.relativePath} (${file.projectLabel})`,
-                file.version || 'N/A'
-            );
-
-            // If user entered something different from current version, store it
-            if (input !== file.version && input !== 'N/A') {
-                if (!validateVersionFormat(input)) {
-                    showWarning(`Invalid version format: ${input} — skipping ${file.relativePath}`);
-                    continue;
-                }
-                file.targetVersion = input;
-            }
-        }
+    const semverFiles = discovery.files.filter((f) => f.selected);
+    const items = semverFiles.map((file, index) => ({
+        key: `${index}`,
+        label: `${file.relativePath} (${file.projectLabel}) - ${file.version || 'N/A'}`,
+        selected: true
+    }));
 
-        return discovery.files;
-    }
+    const selectedKeys = await promptToggleList(
+        'Select files to update (type number to toggle, Enter to confirm):',
+        items
+    );
 
-    return discovery.files;
+    return semverFiles.filter((_, index) => selectedKeys.includes(`${index}`));
 }
 
 /**
@@ -464,20 +414,25 @@ export async function runBumpVersion(args) {
 
     showSuccess('Prerequisites validated');
 
-    // Library verification gate — silent on clean, loud-warn on stale, never-hard-fail
-    logger.debug('bump-version', 'Running Library verification gate');
-    try {
-        const { verify } = await import('../../.library/librarian/index.js');
-        const verifyResult = await verify();
+    // Library verification gate — silent on clean, loud-warn on stale, never-hard-fail.
+    // Only runs when the working repo has its own .library/ (the tool ships without one).
+    if (!hasLibrary()) {
+        logger.debug('bump-version', 'No .library/ in current repo — skipping Library verification gate');
+    } else {
+        logger.debug('bump-version', 'Running Library verification gate');
+        try {
+            const { verify } = await import(libraryModuleUrl('librarian/index.js'));
+            const verifyResult = await verify();
 
-        if (verifyResult.clean) {
-            logger.debug('bump-version', 'Library is clean — no warning needed');
-        } else {
-            _emitLibraryWarning(verifyResult);
+            if (verifyResult.clean) {
+                logger.debug('bump-version', 'Library is clean — no warning needed');
+            } else {
+                _emitLibraryWarning(verifyResult);
+            }
+        } catch (verifyErr) {
+            const msg = `\n${colors.yellow}  ${LIBRARY_VERIFY_SKIPPED_WARNING} ${verifyErr.message}${colors.reset}\n\n`;
+            process.stderr.write(msg);
         }
-    } catch (verifyErr) {
-        const msg = `\n${colors.yellow}  ${LIBRARY_VERIFY_SKIPPED_WARNING} ${verifyErr.message}${colors.reset}\n\n`;
-        process.stderr.write(msg);
     }
 
     // Step 2: Discover all version files
@@ -504,15 +459,6 @@ export async function runBumpVersion(args) {
     // Display discovery table
     displayDiscoveryTable(discovery);
 
-    const currentVersion = discovery.resolvedVersion;
-
-    if (!currentVersion) {
-        showError('Could not determine current version from discovered files');
-        process.exit(1);
-    }
-
-    showInfo(`Current version: ${currentVersion}`);
-
     // Step 3: File selection (if mismatch or interactive mode)
     let selectedFiles = discovery.files.filter((f) => f.selected);
 
@@ -528,6 +474,22 @@ export async function runBumpVersion(args) {
         console.log('');
     }
 
+    // Derive current version from selected files (not from discovery.resolvedVersion)
+    const selectedVersions = selectedFiles
+        .filter((f) => f.version !== null)
+        .map((f) => f.version);
+    const uniqueSelected = [...new Set(selectedVersions)];
+    const currentVersion = uniqueSelected.length === 1
+        ? uniqueSelected[0]
+        : discovery.resolvedVersion;
+
+    if (!currentVersion) {
+        showError('Could not determine a valid semver version from selected files');
+        process.exit(1);
+    }
+
+    showInfo(`Current version: ${currentVersion}`);
+
     // Step 4: Calculate new version or apply suffix operation
     logger.debug('bump-version', 'Step 4: Calculating new version');
     let newVersion;

package/lib/commands/close-release.js

@@ -35,6 +35,7 @@ import {
     promptEditField
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { resolveLabels } from '../utils/label-resolver.js';
 import { colors, error, checkGitRepo } from './helpers.js';
 
@@ -356,26 +357,31 @@ export async function runCloseRelease(args) {
     console.log('');
 
     try {
-        // Library staleness gate — block release closure if books are stale
-        try {
-            showInfo('📚 Checking library staleness...');
-            const { runAll, formatHuman } = await import('../../.library/tools/staleness.js');
-            const { getSourceDir, getBooksDir } = await import('../../.library/paths.js');
-            const { getRepoRoot } = await import('../utils/git-operations.js');
-            const stalenessResult = await runAll(getBooksDir(), getSourceDir(), getRepoRoot(), false);
-            const hasDrift = stalenessResult.stale.length > 0 ||
-                stalenessResult.orphan_books.length > 0 ||
-                stalenessResult.unbooked_sources.length > 0;
-            if (hasDrift) {
-                error('📚 Library staleness detected — cannot close release with stale books');
-                process.stdout.write(formatHuman(stalenessResult));
-                error('Run: npm run library:regenerate');
-                process.exit(1);
+        // Library staleness gate — block release closure if books are stale.
+        // Only runs when the working repo has its own .library/ (the tool ships without one).
+        if (!hasLibrary()) {
+            logger.debug('close-release', 'No .library/ in current repo — skipping Library staleness gate');
+        } else {
+            try {
+                showInfo('📚 Checking library staleness...');
+                const { runAll, formatHuman } = await import(libraryModuleUrl('tools/staleness.js'));
+                const { getSourceDir, getBooksDir } = await import(libraryModuleUrl('paths.js'));
+                const { getRepoRoot } = await import('../utils/git-operations.js');
+                const stalenessResult = await runAll(getBooksDir(), getSourceDir(), getRepoRoot(), false);
+                const hasDrift = stalenessResult.stale.length > 0 ||
+                    stalenessResult.orphan_books.length > 0 ||
+                    stalenessResult.unbooked_sources.length > 0;
+                if (hasDrift) {
+                    error('📚 Library staleness detected — cannot close release with stale books');
+                    process.stdout.write(formatHuman(stalenessResult));
+                    error('Run: npm run library:regenerate');
+                    process.exit(1);
+                }
+                showSuccess('📚 Library books are current');
+            } catch (err) {
+                showWarning('📚 Library staleness check unavailable — .library/ tools not found');
+                logger.debug('close-release', 'Library staleness check skipped', { error: err.message });
             }
-            showSuccess('📚 Library books are current');
-        } catch (err) {
-            showWarning('📚 Library staleness check unavailable — .library/ tools not found');
-            logger.debug('close-release', 'Library staleness check skipped', { error: err.message });
         }
 
         // ── Step 7: git reset --soft origin/main ─────────────────────────────

package/lib/commands/create-pr.js

@@ -24,6 +24,7 @@ import {
 } from '../utils/interactive-ui.js';
 import { getBranchPushStatus, pushBranch, stageFiles, createCommit, getRepoRoot } from '../utils/git-operations.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl } from '../utils/library-resolver.js';
 import { resolveLabels } from '../utils/label-resolver.js';
 import { CostTracker } from '../utils/cost-tracker.js';
 import { error, fatal, checkGitRepo } from './helpers.js';
@@ -364,7 +365,7 @@ export async function runCreatePr(args) {
         // Step 5.6: Version alignment validation (Issue #44)
         logger.debug('create-pr', 'Step 5.6: Validating version alignment');
         const { validateVersionAlignment } = await import('../utils/version-manager.js');
-        const versionCheck = await validateVersionAlignment();
+        const versionCheck = await validateVersionAlignment(baseBranch);
 
         if (!versionCheck.aligned) {
             showWarning('Version misalignment detected:');
@@ -451,23 +452,163 @@ export async function runCreatePr(args) {
             }
         }
 
-        // Step 5.7: Smart tag pushing (Issue #44)
-        logger.debug('create-pr', 'Step 5.7: Checking and pushing unpushed tags');
+        // Step 5.7: Library maintenance pipeline (AUT-3764)
+        // Runs BEFORE tag push so that library regen is included in the tagged commit.
+        // Guard: only run if the current repo has its own .library/ setup.
+        // When claude-hooks is installed in a foreign repo (npm link / file: ref),
+        // the relative import resolves to git-hooks' .library/ — not this repo's.
+        let libraryCommitted = false;
+        const root = getRepoRoot();
+        const libraryResolverPath = path.join(root, '.library', 'resolver.yaml');
+        if (!fs.existsSync(libraryResolverPath)) {
+            logger.debug('create-pr', 'No .library/resolver.yaml in current repo — skipping Library pipeline');
+        } else {
+            logger.debug('create-pr', 'Step 5.7: Running Library maintenance pipeline');
+            try {
+                showInfo('Running Library maintenance pipeline...');
+                const { createPrPipeline } = await import(libraryModuleUrl('librarian/index.js'));
+
+                const pipelineSummary = await createPrPipeline({ repoRoot: root });
+                const {
+                    modifiedFiles: libraryFiles,
+                    perStep,
+                    pendingDueToApiDown,
+                    warnings: pipelineWarnings,
+                } = pipelineSummary;
+
+                // Surface pipeline summary
+                logger.debug('create-pr', 'Pipeline completed', {
+                    modifiedCount: libraryFiles.length,
+                    pendingDueToApiDown,
+                    warningCount: pipelineWarnings.length,
+                });
+                showInfo(`Staleness: ${perStep.staleness.staleCount} stale, ${perStep.staleness.unbookedCount} unbooked`);
+                if (perStep.regen.changed > 0) {
+                    showInfo(`Regenerated: ${perStep.regen.changed} book(s)`);
+                }
+                if (perStep.addRemoveRename.created > 0) {
+                    showInfo(`Created: ${perStep.addRemoveRename.created} new book(s)`);
+                }
+                if (pendingDueToApiDown > 0) {
+                    showWarning(`Gotchas pending (API down): ${pendingDueToApiDown}`);
+                }
+                for (const w of pipelineWarnings) {
+                    showWarning(w);
+                }
+
+                if (libraryFiles.length === 0) {
+                    showInfo('Library already in sync');
+                } else {
+                    // Stage all modified Library files (stageFiles expects absolute paths)
+                    const absFiles = libraryFiles.map(f => path.join(root, f));
+                    const stageResult = stageFiles(absFiles);
+
+                    if (!stageResult.success) {
+                        showWarning(`Failed to stage Library files: ${stageResult.error}`);
+                    } else {
+                        // Commit with deterministic message — separate commit, not amend
+                        const libraryCommitMsg = `chore(library): sync books for ${currentBranch}`;
+                        const commitResult = createCommit(libraryCommitMsg);
+
+                        if (!commitResult.success) {
+                            showWarning(`Failed to commit Library changes: ${commitResult.error}`);
+                        } else {
+                            libraryCommitted = true;
+                            showSuccess(`Library committed: ${libraryCommitMsg} (${libraryFiles.length} file(s))`);
+
+                            // Push the Library commit to the PR branch's remote
+                            const libraryPushResult = pushBranch(currentBranch);
+                            if (!libraryPushResult.success) {
+                                showWarning(`Failed to push Library commit: ${libraryPushResult.error}`);
+                            } else {
+                                showSuccess('Library commit pushed');
+                            }
+                        }
+                    }
+                }
+            } catch (pipelineErr) {
+                // Pipeline failure is non-blocking — log and continue with PR creation
+                logger.warning('create-pr', 'Library pipeline failed, continuing', {
+                    error: pipelineErr.message,
+                });
+                showWarning(`Library pipeline unavailable: ${pipelineErr.message}`);
+            }
+        }
+
+        // Step 5.75: mscope lessons-learned capture (automation-skills resume).
+        // Interactive knowledge-capture alongside the gotcha solicitation above:
+        // hands stdio to `automation-skills resume`, which records the branch's
+        // lessons to the skill repo's implementation-history.md. Skipped in
+        // headless mode (interactive by nature), config-gated via
+        // skillRegistry.resumeOnCreatePr, and never blocks PR creation.
+        if (!headless &&
+            config.skillRegistry?.enabled !== false &&
+            config.skillRegistry?.resumeOnCreatePr !== false) {
+            try {
+                const { isResumeCliAvailable, runResumeFlow } = await import('../utils/skill-registry/resume.js');
+                if (isResumeCliAvailable()) {
+                    showInfo('Handing control to `automation-skills resume` to capture lessons-learned...');
+                    const resumeOut = runResumeFlow({ repoRoot: root });
+                    if (resumeOut.ran && resumeOut.exitCode === 0) {
+                        showSuccess('Lessons captured to the mscope skill repo');
+                    } else if (resumeOut.ran) {
+                        showWarning('Lessons capture exited without recording (see output above)');
+                    }
+                } else {
+                    logger.debug('create-pr', 'automation-skills CLI not found — skipping lessons capture');
+                }
+            } catch (resumeErr) {
+                // Knowledge capture failure is non-blocking — log and continue.
+                showWarning(`Lessons capture unavailable: ${resumeErr.message}`);
+            }
+        }
+
+        // Step 5.8: Smart tag pushing (Issue #44)
+        // Runs AFTER library maintenance so tags include the library commit.
+        logger.debug('create-pr', 'Step 5.8: Checking and pushing unpushed tags');
         const {
             compareLocalAndRemoteTags,
             pushTags: pushTagsUtil,
-            getLatestLocalTag,
-            getLatestRemoteTag,
+            createTag: createTagUtil,
+            getLatestRemoteTagOnBranch,
             parseTagVersion
         } = await import('../utils/git-tag-manager.js');
         const { compareVersions } = await import('../utils/version-manager.js');
 
+        // If library was committed after bump-version created the tag,
+        // re-point unpushed tags to HEAD so the tag includes library books.
+        if (libraryCommitted) {
+            const unpushedTags = await compareLocalAndRemoteTags();
+            for (const tag of unpushedTags.localNewer) {
+                const version = parseTagVersion(tag);
+                if (version) {
+                    logger.debug('create-pr', 'Re-pointing tag to include library commit', { tag });
+                    let origTagMsg = '';
+                    try { origTagMsg = execSync(`git tag -l --format="%(contents)" ${tag}`, { encoding: 'utf8' }).trim(); } catch { /* ignore */ }
+                    const tagMsg = origTagMsg || `Release version ${version}`;
+                    try {
+                        await createTagUtil(version, tagMsg, { force: true });
+                        showInfo(`Tag ${tag} moved to include library commit`);
+                    } catch (tagErr) {
+                        logger.warning('create-pr', 'Failed to re-point tag, continuing', { tag, error: tagErr.message });
+                    }
+                }
+            }
+        }
+
         const tagComparison = await compareLocalAndRemoteTags();
 
         if (tagComparison.localNewer.length > 0) {
-            // Get latest local and remote tags for comparison
-            const latestLocalTag = getLatestLocalTag();
-            const latestRemoteTag = await getLatestRemoteTag();
+            // Derive latest unpushed tag (scoped to what's actually being pushed)
+            const sortedUnpushed = tagComparison.localNewer
+                .map((t) => ({ tag: t, version: parseTagVersion(t) }))
+                .filter((t) => t.version !== null)
+                .sort((a, b) => compareVersions(a.version, b.version));
+            const latestLocalTag = sortedUnpushed.length > 0
+                ? sortedUnpushed[sortedUnpushed.length - 1].tag
+                : tagComparison.localNewer[0];
+            // Compare against latest remote tag on the BASE branch (not global latest)
+            const latestRemoteTag = getLatestRemoteTagOnBranch(baseBranch);
 
             const localVersion = latestLocalTag ? parseTagVersion(latestLocalTag) : null;
             const remoteVersion = latestRemoteTag ? parseTagVersion(latestRemoteTag) : null;
@@ -483,7 +624,7 @@ export async function runCreatePr(args) {
             let shouldPushTags = false;
             let userChoice = null;
 
-            // Case 1: Local tag > Remote tag → Auto-push
+            // Case 1: Local tag > Remote tag → Auto-push (normal bump-version flow)
             if (localVersion && remoteVersion && compareVersions(localVersion, remoteVersion) > 0) {
                 logger.debug('create-pr', 'Local version > remote version, auto-pushing', {
                     localVersion,
@@ -494,7 +635,7 @@ export async function runCreatePr(args) {
                 showInfo('Auto-pushing tag to remote...');
                 shouldPushTags = true;
 
-                // Case 2: Local tag = Remote tag → Prompt with warning
+                // Case 2: Local tag = Remote tag → Prompt with warning (may already be pushed)
             } else if (
                 localVersion &&
                 remoteVersion &&
@@ -534,7 +675,7 @@ export async function runCreatePr(args) {
                     shouldPushTags = true;
                 }
 
-                // Case 3: Local tag < Remote tag → Prompt with error
+                // Case 3: Local tag < Remote tag → Prompt with warning (someone pushed newer)
             } else if (
                 localVersion &&
                 remoteVersion &&
@@ -664,78 +805,6 @@ export async function runCreatePr(args) {
             logger.debug('create-pr', 'No unpushed tags found, continuing');
         }
 
-        // Step 5.8: Library maintenance pipeline (AUT-3764)
-        logger.debug('create-pr', 'Step 5.8: Running Library maintenance pipeline');
-        try {
-            showInfo('Running Library maintenance pipeline...');
-            const { createPrPipeline } = await import('../../.library/librarian/index.js');
-            const root = getRepoRoot();
-
-            const pipelineSummary = await createPrPipeline({ repoRoot: root });
-            const {
-                modifiedFiles: libraryFiles,
-                perStep,
-                pendingDueToApiDown,
-                warnings: pipelineWarnings,
-            } = pipelineSummary;
-
-            // Surface pipeline summary
-            logger.debug('create-pr', 'Pipeline completed', {
-                modifiedCount: libraryFiles.length,
-                pendingDueToApiDown,
-                warningCount: pipelineWarnings.length,
-            });
-            showInfo(`Staleness: ${perStep.staleness.staleCount} stale, ${perStep.staleness.unbookedCount} unbooked`);
-            if (perStep.regen.changed > 0) {
-                showInfo(`Regenerated: ${perStep.regen.changed} book(s)`);
-            }
-            if (perStep.addRemoveRename.created > 0) {
-                showInfo(`Created: ${perStep.addRemoveRename.created} new book(s)`);
-            }
-            if (pendingDueToApiDown > 0) {
-                showWarning(`Gotchas pending (API down): ${pendingDueToApiDown}`);
-            }
-            for (const w of pipelineWarnings) {
-                showWarning(w);
-            }
-
-            if (libraryFiles.length === 0) {
-                showInfo('Library already in sync');
-            } else {
-                // Stage all modified Library files (stageFiles expects absolute paths)
-                const absFiles = libraryFiles.map(f => path.join(root, f));
-                const stageResult = stageFiles(absFiles);
-
-                if (!stageResult.success) {
-                    showWarning(`Failed to stage Library files: ${stageResult.error}`);
-                } else {
-                    // Commit with deterministic message — separate commit, not amend
-                    const libraryCommitMsg = `chore(library): sync books for ${currentBranch}`;
-                    const commitResult = createCommit(libraryCommitMsg);
-
-                    if (!commitResult.success) {
-                        showWarning(`Failed to commit Library changes: ${commitResult.error}`);
-                    } else {
-                        showSuccess(`Library committed: ${libraryCommitMsg} (${libraryFiles.length} file(s))`);
-
-                        // Push the Library commit to the PR branch's remote
-                        const libraryPushResult = pushBranch(currentBranch);
-                        if (!libraryPushResult.success) {
-                            showWarning(`Failed to push Library commit: ${libraryPushResult.error}`);
-                        } else {
-                            showSuccess('Library commit pushed');
-                        }
-                    }
-                }
-            }
-        } catch (pipelineErr) {
-            // Pipeline failure is non-blocking — log and continue with PR creation
-            logger.warning('create-pr', 'Library pipeline failed, continuing', {
-                error: pipelineErr.message,
-            });
-            showWarning(`Library pipeline unavailable: ${pipelineErr.message}`);
-        }
-
         // Step 6: Generate PR metadata using engine
         logger.debug('create-pr', 'Step 6: Generating PR metadata with engine');
         showInfo('Generating PR metadata with Claude...');

package/lib/commands/create-release.js

@@ -59,6 +59,7 @@ import {
     promptConfirmation
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { colors, error, checkGitRepo } from './helpers.js';
 import {
     CONSOLE_WARNING_TEMPLATE,
@@ -372,21 +373,26 @@ export async function runCreateRelease(args) {
     showSuccess('Preconditions validated');
     console.log('');
 
-    // Step 2: Library verification gate — silent on clean, loud-warn on stale, never blocks
+    // Step 2: Library verification gate — silent on clean, loud-warn on stale, never blocks.
+    // Only runs when the working repo has its own .library/ (the tool ships without one).
     let verifyResult = null;
-    logger.debug('create-release', 'Step 2: Running Library verification gate');
-    try {
-        const { verify } = await import('../../.library/librarian/index.js');
-        verifyResult = await verify();
+    if (!hasLibrary()) {
+        logger.debug('create-release', 'No .library/ in current repo — skipping Library verification gate');
+    } else {
+        logger.debug('create-release', 'Step 2: Running Library verification gate');
+        try {
+            const { verify } = await import(libraryModuleUrl('librarian/index.js'));
+            verifyResult = await verify();
 
-        if (verifyResult.clean) {
-            logger.debug('create-release', 'Library is clean — no warning needed');
-        } else {
-            _emitLibraryWarning(verifyResult);
+            if (verifyResult.clean) {
+                logger.debug('create-release', 'Library is clean — no warning needed');
+            } else {
+                _emitLibraryWarning(verifyResult);
+            }
+        } catch (verifyErr) {
+            const msg = `\n${colors.yellow}  ${LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE} ${verifyErr.message}${colors.reset}\n\n`;
+            process.stderr.write(msg);
         }
-    } catch (verifyErr) {
-        const msg = `\n${colors.yellow}  ${LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE} ${verifyErr.message}${colors.reset}\n\n`;
-        process.stderr.write(msg);
     }
 
     // Step 3: Discover version files
@@ -511,7 +517,7 @@ export async function runCreateRelease(args) {
             logger.debug('create-release', 'Step 9: Running Library regeneration');
             showInfo('📚 Regenerating stale Library books...');
             try {
-                const { createPrPipeline } = await import('../../.library/librarian/index.js');
+                const { createPrPipeline } = await import(libraryModuleUrl('librarian/index.js'));
                 const root = getRepoRoot();
                 const pipelineSummary = await createPrPipeline({ repoRoot: root });
 

package/lib/commands/help.js

@@ -18,8 +18,6 @@ import { fetchFileContent, fetchDirectoryListing, createIssue } from '../utils/g
 import { promptMenu, promptEditField, promptConfirmation } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { commands } from '../cli-metadata.js';
-import { fetchLibraryContent as librarianFetch } from '../../.library/librarian/index.js';
-
 /**
  * Get claude-hooks source repo coordinates from package.json
  * Why: AI help must always fetch from the tool's own repo, not the user's current repo
@@ -192,10 +190,22 @@ const _readPackageFile = async (relativePath) => {
  * Why: The catalog provides navigational context for the AI librarian (Pass 1).
  * Delegates to the librarian module for directory discovery and routing.
  *
+ * Uses dynamic import() because .library/ is not shipped in the npm package —
+ * it only exists in the source repo. When running from a global install,
+ * the import fails gracefully and the help command falls back to static help.
+ *
  * @returns {Promise<string|null>} Concatenated catalog or null if nothing could be read
  */
 const readLibraryCatalog = async () => {
-    // Fetching delegated to the librarian module; see .library/librarian/
+    let librarianFetch;
+    try {
+        const mod = await import('../../.library/librarian/index.js');
+        librarianFetch = mod.fetchLibraryContent;
+    } catch {
+        logger.debug('help - readLibraryCatalog', 'Library not available (expected in global install)');
+        return null;
+    }
+
     try {
         const result = await librarianFetch(null, { repoRoot: _packageRoot, full: true });
         if (result.catalog) {

package/lib/defaults.json

@@ -112,6 +112,11 @@
         "model": "sonnet",
         "timeout": 360000
     },
+    "skillRegistry": {
+        "enabled": true,
+        "blockOn": "never",
+        "resumeOnCreatePr": true
+    },
     "orchestrator": {
         "model": "opus",
         "timeout": 60000,