claude-git-hooks 2.66.1 → 2.67.3

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/defaults.json

@@ -112,6 +112,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 = {

package/lib/utils/config-registry.js

@@ -70,6 +70,7 @@ const SECTION_REMOTE_MAP = {
     analysis: _settingsEntry('analysis'),
     commitMessage: _settingsEntry('commitMessage'),
     judge: _settingsEntry('judge'),
+    skillRegistry: _settingsEntry('skillRegistry'),
     orchestrator: _settingsEntry('orchestrator'),
     prMetadata: _settingsEntry('prMetadata'),
     linting: _settingsEntry('linting')

package/lib/utils/library-resolver.js

@@ -0,0 +1,50 @@
+/**
+ * File: library-resolver.js
+ * Purpose: Resolve the Library (`.library/`) of the repository that claude-hooks
+ *          is currently running in — never the bundled tool's own copy.
+ *
+ * Why: claude-git-hooks is a tool. When installed (globally or as a dependency)
+ * it intentionally ships WITHOUT a `.library/` (see package.json `files`). The
+ * Library that the pipeline maintains always belongs to the repo under work —
+ * e.g. running `create-pr` inside `mscope-transactions` maintains that repo's
+ * docs. The only time it touches git-hooks' own Library is when dog-fooding
+ * (editing git-hooks itself), in which case the working repo IS git-hooks.
+ *
+ * Consumers must therefore resolve `.library/` from the working repo root, not
+ * relative to their own (package) location. This module centralizes that.
+ *
+ * Cross-platform: getRepoRoot() returns a git path (`/mnt/c/...` under WSL/Linux,
+ * `C:/...` under native Windows). `path.join` + `pathToFileURL` produce a valid
+ * `file://` URL for the current runtime, so `import()` of an absolute path works
+ * everywhere (a bare `import('C:\\...')` is invalid on Windows).
+ *
+ * Dependencies:
+ * - git-operations: getRepoRoot() — the single source of truth for the repo root
+ */
+
+import { existsSync } from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { getRepoRoot } from './git-operations.js';
+
+/**
+ * Build a file:// URL for a module inside the current repo's `.library/`,
+ * suitable for dynamic `import()`.
+ *
+ * @param {string} subpath - Path inside `.library/` (e.g. 'librarian/index.js')
+ * @returns {string} A `file://` URL string
+ */
+export function libraryModuleUrl(subpath) {
+    return pathToFileURL(path.join(getRepoRoot(), '.library', subpath)).href;
+}
+
+/**
+ * Whether the current repo has its own Library to maintain.
+ * Cheap pre-check so consumers can skip the pipeline cleanly (no scary warning)
+ * in repos that simply have no `.library/`.
+ *
+ * @returns {boolean} True when `.library/resolver.yaml` exists in the repo root
+ */
+export function hasLibrary() {
+    return existsSync(path.join(getRepoRoot(), '.library', 'resolver.yaml'));
+}

package/lib/utils/prompt-builder.js

@@ -194,6 +194,8 @@ const formatFileSection = ({ path, diff, content, isNew }) => {
  * @param {Object} options.metadata - Additional metadata (repo name, branch, etc.)
  * @param {string|null} options.commonContext - Shared commit overview injected before file diffs (optional)
  * @param {string|null} options.batchRationale - Orchestrator's rationale for this batch (optional)
+ * @param {string|null} options.catalogueSection - Rendered platform antipattern catalogue (optional;
+ *                      callers obtain it via skill-registry getCatalogueSection())
  * @returns {Promise<string>} Complete analysis prompt
  *
  * File data object structure:
@@ -211,6 +213,7 @@ const buildAnalysisPrompt = async ({
     metadata = {},
     commonContext = null,
     batchRationale = null,
+    catalogueSection = null,
     baseDir = '.claude/prompts'
 } = {}) => {
     logger.debug('prompt-builder - buildAnalysisPrompt', 'Building analysis prompt', {
@@ -219,6 +222,7 @@ const buildAnalysisPrompt = async ({
         fileCount: files.length,
         hasCommonContext: !!commonContext,
         hasBatchRationale: !!batchRationale,
+        hasCatalogueSection: !!catalogueSection,
         baseDir
     });
 
@@ -247,6 +251,17 @@ const buildAnalysisPrompt = async ({
         prompt += '\n\n=== EVALUATION GUIDELINES ===\n';
         prompt += guidelines;
 
+        // Add the mscope platform antipattern catalogue if the caller supplied
+        // one (rendered via skill-registry getCatalogueSection()). The catalogue
+        // lists every JBE-NNN / UIK-NNN / etc. rule with severity; Claude is
+        // instructed to populate details[].rule with the catalogue ID when a
+        // finding matches. Unmatched findings (rule unset) become skill-gap
+        // candidates downstream.
+        if (catalogueSection) {
+            prompt += '\n\n=== PLATFORM ANTIPATTERN CATALOGUE ===\n';
+            prompt += catalogueSection;
+        }
+
         // Add changes section
         prompt += '\n\n=== CHANGES TO REVIEW ===\n';
 

package/lib/utils/skill-registry/catalogue.js

@@ -0,0 +1,74 @@
+/**
+ * File: skill-registry/catalogue.js
+ * Purpose: Render the parsed JBE/UIK rule index as a compact catalogue
+ *          string suitable for injection into Claude's analysis prompt.
+ *
+ * Why this exists (Option E2): when Claude analyses code, we want it to
+ * label findings with the canonical rule ID (e.g. `JBE-001`) directly,
+ * rather than relying on fuzzy post-processing to guess. We do this by
+ * injecting a compact catalogue into the analysis prompt — one line per
+ * rule, grouped by scope, ~80 chars per line. The prompt's existing
+ * `details[].rule` field (already declared "optional" in the schema)
+ * becomes load-bearing: populated = covered; empty = skill-gap candidate.
+ *
+ * Token budget: ~95 rules × ~80 chars = ~7.6 KB → ~1,900 tokens added to
+ * each analysis prompt. Negligible against the 200k context window.
+ *
+ * Why a separate module: keeps catalogue formatting decisions (one-line
+ * vs full, severity tags, scope grouping) in one place where they can be
+ * tuned without touching prompt-builder or pre-commit.
+ */
+
+/**
+ * Render the rule catalogue as a compact string for prompt injection.
+ * @param {Array<object>} rules - From parser.loadRegistry().rules
+ * @returns {string} catalogue text (empty string if no rules)
+ */
+export function renderCatalogue(rules) {
+    if (!rules || rules.length === 0) return '';
+
+    const byScope = {};
+    for (const r of rules) {
+        (byScope[r.scope] ||= []).push(r);
+    }
+
+    const lines = [];
+    lines.push('Each finding MUST be classified against the platform antipattern catalogue below.');
+    lines.push('When a finding matches a catalogue entry, populate `details[].rule` with the rule ID');
+    lines.push('(e.g. "JBE-001"). Findings that don\'t match any entry leave `rule` empty — those');
+    lines.push('are candidate skill-gaps the team will review separately.');
+    lines.push('');
+
+    const SCOPE_LABELS = {
+        backend: 'BACKEND (Java / Spring Boot / JPA / SQL Server) — applies to .java and .sql files',
+        frontend: 'FRONTEND (React / @mscope/uikit / RHF / TanStack Query) — applies to .jsx/.tsx/.js/.css',
+    };
+
+    for (const scope of ['backend', 'frontend']) {
+        const list = byScope[scope];
+        if (!list || list.length === 0) continue;
+        lines.push(SCOPE_LABELS[scope] || scope.toUpperCase());
+
+        // Sort: id ascending (group prefix together: JBE-001..JBE-NNN, UIK-001..)
+        list.sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+
+        for (const r of list) {
+            const sevTag = (`[${  r.severity || 'unknown'  }]`).padEnd(11);
+            const title = (r.title || '').replace(/`/g, '').slice(0, 110);
+            lines.push(`  ${r.id.padEnd(9)} ${sevTag} ${title}`);
+        }
+        lines.push('');
+    }
+
+    lines.push('SEVERITY → JSON mapping:');
+    lines.push('  critical → BLOCKER  (commit blocked)');
+    lines.push('  high     → CRITICAL (commit blocked)');
+    lines.push('  medium   → MAJOR    (warn)');
+    lines.push('  low      → MINOR    (warn)');
+    lines.push('');
+    lines.push('When you flag a finding, the catalogue entry\'s severity tells you the MIN severity');
+    lines.push('to assign — don\'t downgrade. You may upgrade if context warrants (e.g. a JBE-001');
+    lines.push('printStackTrace inside a financial calculation path is BLOCKER, not CRITICAL).');
+
+    return lines.join('\n');
+}