claude-git-hooks 2.61.2 → 2.67.3

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/messages/library-warnings.js

@@ -1,11 +1,15 @@
 /**
  * File: library-warnings.js
- * Purpose: Warning wording for Library verification gates in claude-hooks.
+ * Purpose: Staleness-warning wording and rendering for Library verification
+ *          gates in claude-hooks.
  *
- * Staleness wording is canonical in the librarian messages module
- * (.library/librarian/messages/staleness-warnings.js) — this file
- * re-exports it for claude-hooks consumers. Do not edit wording here;
- * edit the librarian template instead.
+ * These are consumer rendering functions — they take structured VerifyResult
+ * data from the Library and produce display-ready text (console) or Markdown
+ * (PR body). The Library produces the data; this module formats it.
+ *
+ * Constraints:
+ *   - Pure functions of (VerifyResult, opts) — no I/O, no globals, no environment
+ *   - Do NOT import from .library/ — lib/ must not depend on unshipped paths
  *
  * Related tickets:
  *   AUT-3767 — original placeholder (retired by AUT-3769)
@@ -14,11 +18,125 @@
  *   AUT-3738 — parent user story
  */
 
-export {
-    CONSOLE_WARNING_TEMPLATE,
-    PR_BODY_SECTION_TEMPLATE,
-    PR_TAG_VALUE
-} from '../../.library/librarian/messages/staleness-warnings.js';
+/**
+ * Render an assertive console warning for Library staleness.
+ *
+ * Returns plain text with a marker and the list of stale books.
+ * The closing section varies by consumer context via `opts.autoRegen`:
+ *   - `'will-run'`  — create-release: regen runs in the same command
+ *   - `'deferred'`  — bump-version: regen runs later via create-pr
+ *
+ * Consumers apply visual formatting (box, color, stderr routing) on top.
+ *
+ * Returns an empty string when the Library is clean.
+ *
+ * @param {Object} verifyResult
+ * @param {boolean}      verifyResult.clean
+ * @param {Array<{ path: string, reasons: string[] }>} verifyResult.staleBooks
+ * @param {string[]}     verifyResult.recommendedScripts
+ * @param {Object}       opts
+ * @param {'will-run'|'deferred'} opts.autoRegen — controls the call-to-action
+ * @returns {string} Plain-text console warning, or empty string if clean
+ */
+export function CONSOLE_WARNING_TEMPLATE(verifyResult, opts = {}) {
+    if (verifyResult.clean) {
+        return '';
+    }
+
+    const lines = [];
+
+    lines.push('⚠️  Library is stale');
+    lines.push('');
+    lines.push('The following books are out of date:');
+    lines.push('');
+
+    for (const book of verifyResult.staleBooks) {
+        lines.push(`  • ${book.path}`);
+        for (const reason of book.reasons) {
+            lines.push(`    - ${reason}`);
+        }
+    }
+
+    lines.push('');
+
+    if (opts.autoRegen === 'will-run') {
+        lines.push('Auto-regeneration will run before the release is tagged.');
+    } else if (opts.autoRegen === 'deferred') {
+        lines.push('Library will be auto-regenerated when you run create-pr.');
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Render a Markdown section for the PR body when Library is stale.
+ *
+ * The section heading is exactly `## ⚠️ Library is stale` — do not
+ * change this; downstream tooling may key on it. Includes stale-books
+ * list with reasons and a remediation section that varies by
+ * `opts.autoRegen`:
+ *   - `'completed'` — auto-regen ran successfully; no scripts listed
+ *   - `'failed'`    — auto-regen failed; scripts listed as fallback
+ *
+ * The acknowledgement line is always present.
+ *
+ * Returns an empty string when the Library is clean.
+ *
+ * @param {Object} verifyResult
+ * @param {boolean}      verifyResult.clean
+ * @param {Array<{ path: string, reasons: string[] }>} verifyResult.staleBooks
+ * @param {string[]}     verifyResult.recommendedScripts
+ * @param {Object}       opts
+ * @param {'completed'|'failed'} opts.autoRegen — controls the remediation section
+ * @returns {string} Markdown section, or empty string if clean
+ */
+export function PR_BODY_SECTION_TEMPLATE(verifyResult, opts = {}) {
+    if (verifyResult.clean) {
+        return '';
+    }
+
+    const lines = [];
+
+    lines.push('## ⚠️ Library is stale');
+    lines.push('');
+    lines.push('The following Library books are out of date:');
+    lines.push('');
+
+    for (const book of verifyResult.staleBooks) {
+        const reasonText = book.reasons.join('; ');
+        lines.push(`- \`${book.path}\` — ${reasonText}`);
+    }
+
+    lines.push('');
+
+    if (opts.autoRegen === 'completed') {
+        lines.push('**Auto-regeneration was performed.** The books listed above were regenerated in the release commit.');
+    } else if (opts.autoRegen === 'failed') {
+        lines.push('**Recommended remediation scripts:**');
+        lines.push('');
+        for (const script of verifyResult.recommendedScripts) {
+            lines.push(`- \`${script}\``);
+        }
+        lines.push('');
+        lines.push('_Auto-regeneration was attempted but failed. Run the scripts manually._');
+    }
+
+    lines.push('');
+    lines.push(
+        '_This release was tagged via claude-hooks. The Library lifecycle pipeline is integrated with `create-pr` and `back-merge` — staleness at release time indicates a path that bypassed the pipeline._'
+    );
+
+    return lines.join('\n');
+}
+
+/**
+ * Tag value used to mark a PR or Linear issue as library-stale.
+ *
+ * Applied as a Linear label slug or a PR-title prefix by consumers.
+ *
+ * @type {string}
+ */
+export const PR_TAG_VALUE = 'library-stale';
 
 export const LIBRARY_VERIFY_SKIPPED_WARNING =
     'Library verification skipped due to an unexpected error. ' +

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/claude-client.js

@@ -502,10 +502,11 @@ async function verifySDKConnection() {
  * @param {number} options.timeout - Timeout in milliseconds (default: 120000 = 2 minutes)
  * @param {string} options.model - Claude model override (e.g., 'haiku', 'sonnet', 'opus')
  * @param {boolean} options.headless - Use SDK instead of CLI (default: false)
+ * @param {boolean} options.print - Use CLI print mode (-p): text-only output, no tool use (default: false)
  * @returns {Promise<string>} Claude's response
  * @throws {ClaudeClientError} If execution fails or times out
  */
-const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null, headless = false, maxTokens = null, costTracker = null } = {}) => {
+const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null, headless = false, maxTokens = null, costTracker = null, print = false } = {}) => {
     // Headless mode: use Anthropic SDK directly (GH#133)
     // Branch here (not in executeClaudeWithRetry) because analyzeCode calls
     // executeClaude directly via withRetry — branching here covers all paths.
@@ -548,10 +549,14 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = nu
             // executed inside bash --login so that .profile/.bashrc set up the correct PATH.
             // All CLI flags are embedded in the bash -c command string (no spaces in flag values).
             const claudeParts = [loginShell.path];
+            if (print) claudeParts.push('-p');
             if (allowedTools.length > 0) claudeParts.push(`--allowedTools ${allowedTools.join(',')}`);
             if (model) claudeParts.push(`--model ${model}`);
             finalArgs.push('bash', '-lc', claudeParts.join(' '));
         } else {
+            if (print) {
+                finalArgs.push('-p');
+            }
             if (allowedTools.length > 0) {
                 // Format: --allowedTools "mcp__github__create_pull_request,mcp__github__get_file_contents"
                 finalArgs.push('--allowedTools', allowedTools.join(','));

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/git-tag-manager.js

@@ -196,6 +196,51 @@ export function getLatestLocalTag() {
     }
 }
 
+/**
+ * Gets latest local tag reachable from HEAD
+ * Why: Excludes rogue tags from unrelated branches that were fetched locally
+ *
+ * @returns {string|null} Latest semver tag reachable from HEAD, or null
+ */
+export function getLatestLocalTagOnBranch() {
+    logger.debug('git-tag-manager - getLatestLocalTagOnBranch', 'Getting latest local tag on HEAD');
+
+    try {
+        const output = execGitTagCommand('git tag --merged HEAD --sort=-v:refname');
+
+        if (!output) {
+            logger.debug('git-tag-manager - getLatestLocalTagOnBranch', 'No tags on HEAD');
+            return null;
+        }
+
+        const tags = output.split(/\r?\n/).filter((t) => t.length > 0);
+        const semverTags = tags.filter(isSemverTag);
+
+        if (semverTags.length === 0) {
+            logger.debug('git-tag-manager - getLatestLocalTagOnBranch', 'No semver tags on HEAD', {
+                totalTags: tags.length
+            });
+            return null;
+        }
+
+        const latestTag = semverTags[0];
+
+        logger.debug('git-tag-manager - getLatestLocalTagOnBranch', 'Latest tag on HEAD', {
+            latestTag,
+            semverTags: semverTags.length
+        });
+
+        return latestTag;
+    } catch (error) {
+        logger.error(
+            'git-tag-manager - getLatestLocalTagOnBranch',
+            'Failed to get tags on HEAD',
+            error
+        );
+        return null;
+    }
+}
+
 /**
  * Gets all remote tags
  * Why: Compare local tags with remote for push status
@@ -311,6 +356,65 @@ export async function getLatestRemoteTag(remoteName = null) {
     }
 }
 
+/**
+ * Gets latest remote tag reachable from a specific branch
+ * Why: Scoped comparison — avoids rogue tags pushed from unmerged feature branches
+ *
+ * @param {string} baseBranch - Branch to scope tags to (e.g., 'develop')
+ * @param {string} remoteName - Remote name (default: 'origin')
+ * @returns {string|null} Latest semver tag name reachable from the branch, or null
+ */
+export function getLatestRemoteTagOnBranch(baseBranch, remoteName = null) {
+    const remote = remoteName || getRemoteName();
+    logger.debug('git-tag-manager - getLatestRemoteTagOnBranch', 'Getting latest tag on branch', {
+        baseBranch,
+        remote
+    });
+
+    try {
+        // Ensure remote branch ref is fresh
+        execGitTagCommand(`git fetch ${remote} ${baseBranch} --quiet`);
+
+        // Get tags merged into the remote branch, sorted by version descending
+        const output = execGitTagCommand(
+            `git tag --merged ${remote}/${baseBranch} --sort=-v:refname`
+        );
+
+        if (!output) {
+            logger.debug('git-tag-manager - getLatestRemoteTagOnBranch', 'No tags on branch');
+            return null;
+        }
+
+        const tags = output.split(/\r?\n/).filter((line) => line.length > 0);
+        const semverTags = tags.filter(isSemverTag);
+
+        if (semverTags.length === 0) {
+            logger.debug('git-tag-manager - getLatestRemoteTagOnBranch', 'No semver tags on branch', {
+                totalTags: tags.length
+            });
+            return null;
+        }
+
+        // Already sorted by git --sort=-v:refname (descending), first is latest
+        const latestTag = semverTags[0];
+
+        logger.debug('git-tag-manager - getLatestRemoteTagOnBranch', 'Latest tag on branch', {
+            baseBranch,
+            latestTag,
+            semverTags: semverTags.length
+        });
+
+        return latestTag;
+    } catch (error) {
+        logger.error(
+            'git-tag-manager - getLatestRemoteTagOnBranch',
+            'Failed to get tags on branch',
+            error
+        );
+        return null;
+    }
+}
+
 /**
  * Checks if tag exists
  * Why: Prevents duplicate tag creation

package/lib/utils/judge.js

@@ -139,7 +139,8 @@ const judgeAndFix = async (analysisResult, filesData, config, { headless = false
     const response = await executeClaudeWithRetry(prompt, {
         model,
         timeout: judgeTimeout,
-        headless
+        headless,
+        print: true
     });
 
     const parsed = extractJSON(response);

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';