claude-git-hooks 2.66.1 → 2.68.0

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';
@@ -465,7 +466,7 @@ export async function runCreatePr(args) {
             logger.debug('create-pr', 'Step 5.7: Running Library maintenance pipeline');
             try {
                 showInfo('Running Library maintenance pipeline...');
-                const { createPrPipeline } = await import('../../.library/librarian/index.js');
+                const { createPrPipeline } = await import(libraryModuleUrl('librarian/index.js'));
 
                 const pipelineSummary = await createPrPipeline({ repoRoot: root });
                 const {
@@ -534,6 +535,34 @@ export async function runCreatePr(args) {
             }
         }
 
+        // 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');

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/install.js

@@ -27,10 +27,9 @@ import {
     getGitHooksPath,
     isWindows,
     getClaudeCommand,
-    getPackageJson,
-    getLatestVersion,
     Entertainment
 } from './helpers.js';
+import { getUpdateStatus, performUpdate } from '../utils/auto-update.js';
 import { runSetupGitHub } from './setup-github.js';
 import { generateCompletionData } from '../cli-metadata.js';
 import { getConfig } from '../config.js';
@@ -41,11 +40,12 @@ import { getConfig } from '../config.js';
  */
 async function checkVersionAndPromptUpdate() {
     try {
-        const currentVersion = getPackageJson().version;
-        const latestVersion = await getLatestVersion('claude-git-hooks');
+        const { currentVersion, latestVersion, isNewer } = await getUpdateStatus();
 
-        if (currentVersion === latestVersion) {
-            return true; // Already updated
+        // isNewer guards against the `===` downgrade bug: a dev build ahead of npm
+        // (current > latest) must NOT prompt to "update" to an older published version.
+        if (!isNewer) {
+            return true; // Already on latest (or a dev build ahead of npm)
         }
 
         console.log('');
@@ -58,13 +58,13 @@ async function checkVersionAndPromptUpdate() {
         });
 
         return new Promise((resolve) => {
-            rl.question('Do you want to update now? (y/n): ', (answer) => {
+            rl.question('Do you want to update now? (y/n): ', async (answer) => {
                 rl.close();
 
                 if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
-                    info('Updating claude-git-hooks...');
                     try {
-                        execSync('npm install -g claude-git-hooks@latest', { stdio: 'inherit' });
+                        // install is about to run, so skip the hook reinstall here
+                        await performUpdate({ reinstallHooks: false, silent: false });
                         success('Update completed. Please run your command again.');
                         process.exit(0); // Exit so user restarts the process
                     } catch (e) {
@@ -463,16 +463,6 @@ export async function runInstall(args) {
         success(`${hook} installed`);
     });
 
-    // Copy version verification script with LF line endings
-    const checkVersionSource = path.join(templatesPath, 'check-version.sh');
-    const checkVersionDest = path.join(hooksPath, 'check-version.sh');
-
-    if (fs.existsSync(checkVersionSource)) {
-        copyWithLF(checkVersionSource, checkVersionDest);
-        fs.chmodSync(checkVersionDest, '755');
-        success('Version verification script installed');
-    }
-
     // Create .claude directory if it doesn't exist
     const claudeDir = '.claude';
     if (!fs.existsSync(claudeDir)) {

package/lib/commands/update.js

@@ -1,19 +1,13 @@
 /**
  * File: update.js
  * Purpose: Update command - update to the latest version
+ *
+ * Thin wrapper over the shared auto-update logic in lib/utils/auto-update.js.
+ * Runs verbosely (silent: false) — this is a user-initiated update.
  */
 
-import { execSync } from 'child_process';
-import {
-    error,
-    success,
-    info,
-    warning,
-    getPackageJson,
-    getLatestVersion,
-    compareVersions
-} from './helpers.js';
-import { runInstall } from './install.js';
+import { error, success, info, warning } from './helpers.js';
+import { getUpdateStatus, performUpdate } from '../utils/auto-update.js';
 
 /**
  * Update command - update to the latest version
@@ -22,33 +16,26 @@ export async function runUpdate() {
     info('Checking latest available version...');
 
     try {
-        const currentVersion = getPackageJson().version;
-        const latestVersion = await getLatestVersion('claude-git-hooks');
+        const { currentVersion, latestVersion, isNewer, isDev } = await getUpdateStatus();
 
-        const comparison = compareVersions(currentVersion, latestVersion);
-
-        if (comparison === 0) {
-            success(`You already have the latest version installed (${currentVersion})`);
-            return;
-        } else if (comparison > 0) {
+        if (isDev) {
             info(`You are using a development version (${currentVersion})`);
             info(`Latest published version: ${latestVersion}`);
             success(`You already have the latest version installed (${currentVersion})`);
             return;
         }
 
+        if (!isNewer) {
+            success(`You already have the latest version installed (${currentVersion})`);
+            return;
+        }
+
         info(`Current version: ${currentVersion}`);
         info(`Available version: ${latestVersion}`);
 
-        // Update the package
-        info('Updating claude-git-hooks...');
         try {
-            execSync('npm install -g claude-git-hooks@latest', { stdio: 'inherit' });
+            await performUpdate({ reinstallHooks: true, silent: false });
             success(`Successfully updated to version ${latestVersion}`);
-
-            // Reinstall hooks with the new version
-            info('Reinstalling hooks with the new version...');
-            await runInstall(['--force']);
         } catch (updateError) {
             error('Error updating. Try running: npm install -g claude-git-hooks@latest');
         }
@@ -56,9 +43,8 @@ export async function runUpdate() {
         warning('Could not check the latest available version');
         warning('Trying to update anyway...');
         try {
-            execSync('npm install -g claude-git-hooks@latest', { stdio: 'inherit' });
+            await performUpdate({ reinstallHooks: true, silent: false });
             success('Update completed');
-            await runInstall(['--force']);
         } catch (updateError) {
             error(`Error updating: ${updateError.message}`);
         }

package/lib/defaults.json

@@ -33,6 +33,10 @@
         "debug": false,
         "wslCheckTimeout": 15000
     },
+    "autoUpdate": {
+        "enabled": true,
+        "intervalHours": 24
+    },
     "git": {
         "diffFilter": "ACM"
     },
@@ -112,6 +116,11 @@
         "model": "sonnet",
         "timeout": 360000
     },
+    "skillRegistry": {
+        "enabled": true,
+        "blockOn": "never",
+        "resumeOnCreatePr": true
+    },
     "orchestrator": {
         "model": "opus",
         "timeout": 60000,

package/lib/hooks/pre-commit.js

@@ -19,8 +19,8 @@
  * - resolution-prompt: Issue resolution generation
  */
 
-import { join } from 'path';
-import { getStagedFiles, getRepoRoot, getStagedTreeSha } from '../utils/git-operations.js';
+import { join, basename } from 'path';
+import { getStagedFiles, getRepoRoot, getStagedTreeSha, getCurrentBranch } from '../utils/git-operations.js';
 import { writeMarker } from '../utils/hooks-verified-marker.js';
 import { filterFiles } from '../utils/file-operations.js';
 import {
@@ -33,9 +33,11 @@ import { generateResolutionPrompt, shouldGeneratePrompt } from '../utils/resolut
 import { loadPreset } from '../utils/preset-loader.js';
 import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { getConfig } from '../config.js';
 import { recordMetric } from '../utils/metrics.js';
 import { runLinters, displayLintResults, lintIssuesToAnalysisDetails } from '../utils/linter-runner.js';
+import * as skillRegistry from '../utils/skill-registry/index.js';
 
 /**
  * Configuration loaded from lib/config.js
@@ -151,39 +153,44 @@ const main = async () => {
             process.exit(0);
         }
 
-        // Library staleness check — non-blocking warning
-        try {
-            const { checkBook } = await import('../../.library/tools/staleness.js');
-            const { getBooksDir } = await import('../../.library/paths.js');
-            const booksDir = getBooksDir();
-            const sourceFiles = validFiles
-                .map(f => (typeof f === 'string' ? f : f.path))
-                .filter(p => p.startsWith('lib/'));
-
-            if (sourceFiles.length > 0) {
-                const staleBooks = [];
-                for (const srcPath of sourceFiles) {
-                    const bookName = `${srcPath.replace(/^lib\/(?:.*\/)?/, '').replace(/\.js$/, '')}.md`;
-                    const bookPath = join(booksDir, bookName);
-                    try {
-                        const result = await checkBook(bookPath, getRepoRoot());
-                        if (result.status === 'stale') {
-                            staleBooks.push(result.book);
+        // Library staleness check — non-blocking warning.
+        // Only runs when the working repo has its own .library/ (the tool ships without one).
+        if (!hasLibrary()) {
+            logger.debug('pre-commit', 'No .library/ in current repo — skipping Library staleness check');
+        } else {
+            try {
+                const { checkBook } = await import(libraryModuleUrl('tools/staleness.js'));
+                const { getBooksDir } = await import(libraryModuleUrl('paths.js'));
+                const booksDir = getBooksDir();
+                const sourceFiles = validFiles
+                    .map(f => (typeof f === 'string' ? f : f.path))
+                    .filter(p => p.startsWith('lib/'));
+
+                if (sourceFiles.length > 0) {
+                    const staleBooks = [];
+                    for (const srcPath of sourceFiles) {
+                        const bookName = `${srcPath.replace(/^lib\/(?:.*\/)?/, '').replace(/\.js$/, '')}.md`;
+                        const bookPath = join(booksDir, bookName);
+                        try {
+                            const result = await checkBook(bookPath, getRepoRoot());
+                            if (result.status === 'stale') {
+                                staleBooks.push(result.book);
+                            }
+                        } catch {
+                            // Book doesn't exist or check failed — skip silently
                         }
-                    } catch {
-                        // Book doesn't exist or check failed — skip silently
                     }
-                }
-                if (staleBooks.length > 0) {
-                    logger.warning(`📚 ${staleBooks.length} library book(s) will become stale after this commit`);
-                    for (const book of staleBooks) {
-                        logger.warning(`   └─ ${book}`);
+                    if (staleBooks.length > 0) {
+                        logger.warning(`📚 ${staleBooks.length} library book(s) will become stale after this commit`);
+                        for (const book of staleBooks) {
+                            logger.warning(`   └─ ${book}`);
+                        }
+                        logger.warning('   Run: npm run library:regenerate');
                     }
-                    logger.warning('   Run: npm run library:regenerate');
                 }
+            } catch {
+                logger.warning('📚 Library staleness check unavailable — .library/ tools not found');
             }
-        } catch {
-            logger.warning('📚 Library staleness check unavailable — .library/ tools not found');
         }
 
         // Step 3: Run linters (fast, deterministic — before Claude analysis)
@@ -220,6 +227,43 @@ const main = async () => {
             }
         }
 
+        // Step 3.5: mscope skill-registry check (deterministic; fast; warn-only by default).
+        // The facade runs the JBE-NNN / UIK-NNN catalogue's `Verify:` greps
+        // against the staged file contents, displays findings alongside lint +
+        // AI output, and returns the blockOn gating decision. Exiting on a
+        // blocked commit stays here in the hook — utils never exit.
+        //
+        // Silent skip if the skill repo isn't locatable — the integration is
+        // value-add, never a hard dep.
+        //
+        // skillRoot is hoisted to function-scope so Step 9.5 (skill-gap writer)
+        // can reuse the resolution (registry load is memoized in the facade).
+        let skillRoot = null;
+        let skillCheck = null;
+        if (config.skillRegistry?.enabled !== false) {
+            try {
+                const absPaths = validFiles
+                    .map((f) => (typeof f === 'string' ? f : f.path))
+                    .map((p) => (p.startsWith('/') || /^[A-Za-z]:/.test(p) ? p : join(repoRoot, p)));
+
+                skillCheck = skillRegistry.runSkillChecks(absPaths, { repoRoot, config });
+                skillRoot = skillCheck.skillRoot;
+            } catch (err) {
+                // Never break the hook for skill-registry failures.
+                logger.debug('pre-commit - main', 'Skill registry check failed', { error: err?.message });
+            }
+        }
+
+        // The escape hatch is the config knob — `--no-verify` is
+        // intentionally not advertised (project convention discourages
+        // skipping hooks; the config is the supported override).
+        // process.exit stays outside the try-catch per repo convention.
+        if (skillCheck?.shouldBlock) {
+            logger.error(`Skill registry: ${skillCheck.triggeringCount} finding(s) at or above '${config.skillRegistry?.blockOn}' threshold — commit blocked.`);
+            logger.error('To downgrade the threshold, set config.skillRegistry.blockOn = "never" (or a less strict severity).');
+            process.exit(1);
+        }
+
         // Step 4: Build file data using shared engine
         logger.debug('pre-commit - main', 'Building file data for analysis');
         const filesData = buildFilesData(validFiles, { staged: true });
@@ -232,11 +276,17 @@ const main = async () => {
             logger.info('⚡ Intelligent orchestration: grouping files and assigning models');
         }
 
-        // Step 6: Run analysis using shared engine
+        // Step 6: Run analysis using shared engine. The skill-registry
+        // catalogue (memoized load — free after Step 3.5) lets Claude classify
+        // findings against the mscope rule IDs; unmatched findings become
+        // skill-gap candidates in Step 9.5.
         const result = await runAnalysis(filesData, config, {
             hook: 'pre-commit',
             saveDebug: config.system.debug,
-            headless: isHeadless
+            headless: isHeadless,
+            catalogueSection: config.skillRegistry?.enabled !== false
+                ? skillRegistry.getCatalogueSection({ repoRoot })
+                : null
         });
 
         // Step 7: Display results using shared function
@@ -308,6 +358,36 @@ const main = async () => {
             }
         }
 
+        // Step 9.5: Skill-gap writer (Option E2). For each detail Claude left
+        // un-classified (no detail.rule from the catalogue), append a
+        // `[skill-gap]` candidate to the appropriate skill-feedback.md.
+        // Per the maintainer's `feedback_skill_improvements_user_approval`
+        // rule, we never auto-merge candidates into the registry — they're
+        // surfaced for review during `automation-skills retro`.
+        //
+        // Reuses `skillRoot` resolved in Step 3.5 — no second loadRegistry()
+        // round-trip. Silent skip if the skill repo wasn't found or AI
+        // returned no details.
+        if (config.skillRegistry?.enabled !== false &&
+            skillRoot &&
+            Array.isArray(result.details) && result.details.length > 0) {
+            try {
+                const out = skillRegistry.recordSkillGaps(result, {
+                    skillRoot,
+                    branch: getCurrentBranch(),
+                    repoName: basename(repoRoot),
+                });
+                if (out.written > 0) {
+                    logger.info(`📝 ${out.written} skill-gap candidate(s) recorded to skill-feedback.md (${out.skippedDuplicate} duplicate(s) skipped, ${out.skippedClassified} classified to existing rules).`);
+                    logger.info('   Review with: automation-skills retro');
+                }
+            } catch (err) {
+                // Warning (not debug): a failed write means feedback candidates
+                // were silently lost — the user should know. Commit continues.
+                logger.warning(`Skill-gap writer failed — candidates not recorded: ${err?.message}`);
+            }
+        }
+
         // Step 10: Check quality gate
         const qualityGatePassed = result.QUALITY_GATE === 'PASSED';
         const approved = result.approved !== false;

package/lib/utils/analysis-engine.js

@@ -376,10 +376,12 @@ const ORCHESTRATOR_THRESHOLD = getDefaultSection('orchestrator').threshold;
  * @param {Object} options - Analysis options
  * @param {boolean} options.saveDebug - Save debug output (default: from config)
  * @param {string} options.hook - Hook name for telemetry (default: 'analysis')
+ * @param {string|null} options.catalogueSection - Rendered skill-registry catalogue forwarded
+ *                      to the prompt builder (opaque string; default: null)
  * @returns {Promise<Object>} Analysis result
  */
 export const runAnalysis = async (filesData, config, options = {}) => {
-    const { saveDebug = config.system?.debug, hook = 'analysis', headless = false, costTracker = null } = options;
+    const { saveDebug = config.system?.debug, hook = 'analysis', headless = false, costTracker = null, catalogueSection = null } = options;
 
     if (filesData.length === 0) {
         logger.debug('analysis-engine - runAnalysis', 'No files to analyze');
@@ -425,7 +427,8 @@ export const runAnalysis = async (filesData, config, options = {}) => {
                         BRANCH_NAME: getCurrentBranch()
                     },
                     commonContext,
-                    batchRationale: batch.rationale
+                    batchRationale: batch.rationale,
+                    catalogueSection
                 })
             )
         );
@@ -484,7 +487,8 @@ export const runAnalysis = async (filesData, config, options = {}) => {
             metadata: {
                 REPO_NAME: getRepoName(),
                 BRANCH_NAME: getCurrentBranch()
-            }
+            },
+            catalogueSection
         });
 
         const telemetryContext = {