claude-git-hooks 2.45.0 → 2.61.2

package/lib/commands/create-release.js

@@ -4,18 +4,21 @@
  *
  * Workflow:
  * 1. Validate preconditions (clean tree, on develop, up-to-date, no existing RC)
- * 2. Discover version files — abort on mismatch
- * 3. Calculate next version
- * 4. [dry-run] Preview + return
- * 5. Confirm with user
- * 6. Create RC branch from develop
- * 7. Bump version files + commit (--no-verify)
- * 8. [optional] Generate CHANGELOG
- * 9. Create Git tag (skip if already exists)
- * 10. Push RC branch (unless --skip-push)
- * 11. Deploy to shadow (unless --no-shadow or --skip-push)
- * 12. Return to RC branch
- * 13. Display summary
+ * 2. Library verification gate (non-blocking)
+ * 3. Discover version files — abort on mismatch
+ * 4. Calculate next version
+ * 5. [dry-run] Preview + return
+ * 6. Confirm with user
+ * 7. Create RC branch from develop
+ * 8. Bump version files
+ * 9. [if stale] Library regeneration (keeps tag accurate)
+ * 10. [optional] Generate CHANGELOG
+ * 11. Stage all + commit (--no-verify)
+ * 12. Create Git tag (skip if already exists)
+ * 13. Push RC branch (unless --skip-push)
+ * 14. Create release PR (unless --skip-push or push failed)
+ * 15. Deploy to shadow (unless --no-shadow or --skip-push)
+ * 16. Return to RC branch + display summary
  */
 
 import { execSync } from 'child_process';
@@ -57,6 +60,12 @@ import {
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { colors, error, checkGitRepo } from './helpers.js';
+import {
+    CONSOLE_WARNING_TEMPLATE,
+    PR_BODY_SECTION_TEMPLATE,
+    PR_TAG_VALUE,
+    LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE
+} from '../messages/library-warnings.js';
 
 /** Source branch for RC creation */
 const SOURCE_BRANCH = 'develop';
@@ -264,6 +273,51 @@ function restoreSnapshot(snapshot) {
     });
 }
 
+/**
+ * Emit a loud Library staleness warning to stderr.
+ * Content comes from the canonical template + verify result data.
+ * Formatting uses ANSI codes for visual emphasis on TTY stderr.
+ *
+ * @param {import('../../.library/librarian/index.js').VerifyResult} result
+ * @private
+ */
+function _emitLibraryWarning(result) {
+    const y = colors.yellow;
+    const r = colors.reset;
+    const bar = `${y}${'='.repeat(63)}${r}`;
+    const content = CONSOLE_WARNING_TEMPLATE(result, { autoRegen: 'will-run' });
+
+    const lines = ['', bar, '', `${y}${content}${r}`, '', bar, ''];
+
+    process.stderr.write(lines.join('\n'));
+}
+
+/** Marker comment pair wrapping the staleness section in PR bodies */
+const STALENESS_MARKER_OPEN = '<!-- LIBRARY_STALENESS_SECTION -->';
+const STALENESS_MARKER_CLOSE = '<!-- /LIBRARY_STALENESS_SECTION -->';
+
+/**
+ * Build the release PR body, optionally appending the staleness section.
+ *
+ * @param {string} nextVersion
+ * @param {import('../../.library/librarian/index.js').VerifyResult|null} verifyResult
+ * @param {'completed'|'failed'|null} regenOutcome - result of auto-regeneration
+ * @returns {string}
+ * @private
+ */
+function _buildReleasePrBody(nextVersion, verifyResult, regenOutcome) {
+    let body = `## Release V${nextVersion}\n\nRelease-candidate branch created from \`${SOURCE_BRANCH}\`.`;
+
+    if (verifyResult && !verifyResult.clean) {
+        const section = PR_BODY_SECTION_TEMPLATE(verifyResult, {
+            autoRegen: regenOutcome || 'failed'
+        });
+        body += `\n\n${STALENESS_MARKER_OPEN}\n${section}\n${STALENESS_MARKER_CLOSE}`;
+    }
+
+    return body;
+}
+
 /**
  * create-release command
  * Creates a release-candidate branch from develop, bumps version, and deploys to shadow.
@@ -318,8 +372,25 @@ export async function runCreateRelease(args) {
     showSuccess('Preconditions validated');
     console.log('');
 
-    // Step 2: Discover version files
-    logger.debug('create-release', 'Step 2: Discovering version files');
+    // Step 2: Library verification gate — silent on clean, loud-warn on stale, never blocks
+    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 (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);
+    }
+
+    // Step 3: Discover version files
+    logger.debug('create-release', 'Step 3: Discovering version files');
     const discovery = discoverVersionFiles();
 
     if (discovery.files.length === 0) {
@@ -356,7 +427,7 @@ export async function runCreateRelease(args) {
         process.exit(1);
     }
 
-    // Step 3: Calculate next version
+    // Step 4: Calculate next version
     const nextVersion = incrementVersion(currentVersion, options.bumpType);
     const rcBranch = `${RC_PREFIX}/V${nextVersion}`;
     const tagName = formatTagName(nextVersion);
@@ -366,13 +437,13 @@ export async function runCreateRelease(args) {
     showInfo(`Branch:          ${rcBranch}`);
     console.log('');
 
-    // Step 4: Dry-run
+    // Step 5: Dry-run
     if (options.dryRun) {
         showDryRunPreview({ bumpType: options.bumpType, currentVersion, nextVersion, rcBranch, options });
         return;
     }
 
-    // Step 5: Confirm with user
+    // Step 6: Confirm with user
     const confirmed = await promptConfirmation(
         `Create ${rcBranch} and bump version to ${nextVersion}?`,
         true
@@ -388,8 +459,8 @@ export async function runCreateRelease(args) {
         const config = await getConfig();
         const selectedFiles = discovery.files.filter((f) => f.selected);
 
-        // Step 6: Create RC branch from develop
-        logger.debug('create-release', 'Step 6: Creating RC branch', { rcBranch });
+        // Step 7: Create RC branch from develop
+        logger.debug('create-release', 'Step 7: Creating RC branch', { rcBranch });
         showInfo(`Creating branch ${rcBranch} from ${SOURCE_BRANCH}...`);
         checkoutBranch(rcBranch, { create: true, startPoint: SOURCE_BRANCH });
         showSuccess(`✓ Branch created: ${rcBranch}`);
@@ -408,8 +479,8 @@ export async function runCreateRelease(args) {
             }
         });
 
-        // Step 7: Bump version files
-        logger.debug('create-release', 'Step 7: Bumping version files');
+        // Step 8: Bump version files
+        logger.debug('create-release', 'Step 8: Bumping version files');
         showInfo('Updating version files...');
         try {
             updateVersionFiles(selectedFiles, nextVersion);
@@ -433,10 +504,41 @@ export async function runCreateRelease(args) {
             process.exit(1);
         }
 
-        // Step 8: Optional CHANGELOG
+        // Step 9: Library regeneration (if stale — keeps tag accurate)
+        let libraryFiles = [];
+        let regenOutcome = null;
+        if (verifyResult && !verifyResult.clean) {
+            logger.debug('create-release', 'Step 9: Running Library regeneration');
+            showInfo('📚 Regenerating stale Library books...');
+            try {
+                const { createPrPipeline } = await import('../../.library/librarian/index.js');
+                const root = getRepoRoot();
+                const pipelineSummary = await createPrPipeline({ repoRoot: root });
+
+                libraryFiles = pipelineSummary.modifiedFiles.map(
+                    (f) => path.join(root, f)
+                );
+
+                regenOutcome = 'completed';
+                if (libraryFiles.length > 0) {
+                    showSuccess(`✓ Library regenerated (${libraryFiles.length} file(s))`);
+                } else {
+                    showInfo('Library pipeline ran — no files changed');
+                }
+            } catch (regenErr) {
+                regenOutcome = 'failed';
+                showWarning(`Library regeneration failed: ${regenErr.message}`);
+                logger.debug('create-release', 'Library regen failed', {
+                    error: regenErr.message
+                });
+            }
+            process.stdout.write('\n');
+        }
+
+        // Step 10: Optional CHANGELOG
         let selectedChangelogPath = null;
         if (options.updateChangelog) {
-            logger.debug('create-release', 'Step 8: Generating CHANGELOG');
+            logger.debug('create-release', 'Step 10: Generating CHANGELOG');
             showInfo('Generating CHANGELOG entry...');
             const changelogResult = await generateChangelogEntry({
                 version: nextVersion,
@@ -462,6 +564,9 @@ export async function runCreateRelease(args) {
         logger.debug('create-release', 'Staging and committing version bump');
         showInfo('Staging and committing...');
         const filesToStage = selectedFiles.map((f) => f.path);
+        if (libraryFiles.length > 0) {
+            filesToStage.push(...libraryFiles);
+        }
         if (options.updateChangelog) {
             const changelogPath =
                 selectedChangelogPath || path.join(getRepoRoot(), 'CHANGELOG.md');
@@ -496,8 +601,8 @@ export async function runCreateRelease(args) {
         showSuccess('✓ Version bump committed');
         console.log('');
 
-        // Step 9: Create Git tag (skip silently if already exists)
-        logger.debug('create-release', 'Step 9: Creating Git tag', { tagName });
+        // Step 11: Create Git tag (skip silently if already exists)
+        logger.debug('create-release', 'Step 11: Creating Git tag', { tagName });
         const tagAlreadyExists = await tagExists(tagName, 'local');
         if (tagAlreadyExists) {
             showWarning(`Tag ${tagName} already exists locally — skipping tag creation`);
@@ -511,7 +616,7 @@ export async function runCreateRelease(args) {
         }
         console.log('');
 
-        // Step 10: Push RC branch (unless --skip-push)
+        // Step 12: Push RC branch (unless --skip-push)
         let pushStatus = 'skipped (--skip-push)';
         if (!options.skipPush) {
             showInfo(`Pushing ${rcBranch} to remote...`);
@@ -529,7 +634,66 @@ export async function runCreateRelease(args) {
             console.log('');
         }
 
-        // Step 11: Deploy to shadow (unless --no-shadow or --skip-push)
+        // Step 13: Create release PR (unless --skip-push or push failed)
+        let prUrl = null;
+        if (!options.skipPush && pushStatus === 'pushed') {
+            logger.debug('create-release', 'Step 13: Creating release PR');
+            try {
+                const { createPullRequest, validateToken, findExistingPR } =
+                    await import('../utils/github-api.js');
+                const { parseGitHubRepo } = await import('../utils/github-client.js');
+
+                const tokenValidation = await validateToken();
+                if (!tokenValidation.valid) {
+                    showWarning(
+                        `GitHub token invalid — release PR not created: ${tokenValidation.error}`
+                    );
+                    console.log('');
+                    console.log('Create the PR manually:');
+                    console.log(`  gh pr create --base main --head ${rcBranch}`);
+                } else {
+                    const repoInfo = parseGitHubRepo();
+
+                    // Idempotency: skip if PR already exists for this head → main
+                    const existingPR = await findExistingPR({
+                        owner: repoInfo.owner,
+                        repo: repoInfo.repo,
+                        head: rcBranch,
+                        base: 'main'
+                    });
+
+                    if (existingPR) {
+                        showInfo(`Release PR already exists: ${existingPR.html_url}`);
+                        prUrl = existingPR.html_url;
+                    } else {
+                        const prBody = _buildReleasePrBody(nextVersion, verifyResult, regenOutcome);
+                        const labels = verifyResult && !verifyResult.clean
+                            ? [PR_TAG_VALUE]
+                            : [];
+
+                        const pr = await createPullRequest({
+                            owner: repoInfo.owner,
+                            repo: repoInfo.repo,
+                            title: `Release V${nextVersion}`,
+                            body: prBody,
+                            head: rcBranch,
+                            base: 'main',
+                            labels
+                        });
+                        prUrl = pr.html_url;
+                        showSuccess(`✓ Release PR created: ${prUrl}`);
+                    }
+                }
+            } catch (prErr) {
+                showWarning(`Release PR creation failed: ${prErr.message}`);
+                console.log('');
+                console.log('Create the PR manually:');
+                console.log(`  gh pr create --base main --head ${rcBranch}`);
+            }
+            console.log('');
+        }
+
+        // Step 14: Deploy to shadow (unless --no-shadow or --skip-push)
         let shadowStatus = 'skipped';
         if (options.noShadow) {
             showInfo('Shadow deployment skipped (--no-shadow)');
@@ -551,7 +715,7 @@ export async function runCreateRelease(args) {
             }
         }
 
-        // Step 12: Ensure we land on RC branch
+        // Step 15: Ensure we land on RC branch
         const currentBranchAfter = getCurrentBranch();
         if (currentBranchAfter !== rcBranch) {
             try {
@@ -561,7 +725,7 @@ export async function runCreateRelease(args) {
             }
         }
 
-        // Step 13: Summary
+        // Step 16: Summary
         console.log('');
         console.log(
             `${colors.green}════════════════════════════════════════════════════${colors.reset}`
@@ -579,13 +743,17 @@ export async function runCreateRelease(args) {
             `${colors.blue}Tag:${colors.reset}     ${tagAlreadyExists ? `${tagName} (pre-existing, skipped)` : tagName}`
         );
         console.log(`${colors.blue}Push:${colors.reset}    ${pushStatus}`);
+        console.log(
+            `${colors.blue}PR:${colors.reset}      ${prUrl || 'skipped'}`
+        );
         console.log(`${colors.blue}Shadow:${colors.reset}  ${shadowStatus}`);
         console.log('');
 
         if (options.skipPush) {
             console.log('Next steps:');
             console.log(`  1. Push when ready: git push -u origin ${rcBranch}`);
-            console.log(`  2. Sync shadow:     claude-hooks shadow sync ${rcBranch}`);
+            console.log(`  2. Create PR:       gh pr create --base main --head ${rcBranch}`);
+            console.log(`  3. Sync shadow:     claude-hooks shadow sync ${rcBranch}`);
         } else {
             console.log('Next steps:');
             console.log('  1. Verify shadow deployment is running');

package/lib/commands/help.js

@@ -18,6 +18,7 @@ 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
@@ -170,12 +171,7 @@ const _packageRoot = path.join(__dirname, '..', '..');
  */
 const MAX_BOOKS = 5;
 
-/**
- * Catalog directories within .library/ to auto-discover
- * Why: These contain index and shelf files that form the navigational catalog.
- * books/ is excluded — those are fetched on-demand in Pass 2.
- */
-const _CATALOG_DIRS = ['by-code', 'by-domain', 'by-task-type'];
+// Catalog routing delegated to the librarian module; see .library/librarian/
 
 /**
  * Read a single file from package root, returning null on failure
@@ -194,67 +190,27 @@ const _readPackageFile = async (relativePath) => {
 /**
  * Read the project catalog from .library/ and CLAUDE.md
  * Why: The catalog provides navigational context for the AI librarian (Pass 1).
- * Auto-discovers index/shelf files so the catalog stays current as .library/ grows.
- *
- * Reads:
- * - CLAUDE.md (global rules)
- * - .library/index.md (repo identity, capabilities)
- * - .library/conventions.md (coding standards)
- * - .library/by-code/*.md (source-path shelves)
- * - .library/by-domain/*.md (workflow reading lists)
- * - .library/by-task-type/*.md (task guidance)
+ * Delegates to the librarian module for directory discovery and routing.
  *
  * @returns {Promise<string|null>} Concatenated catalog or null if nothing could be read
  */
 const readLibraryCatalog = async () => {
-    const sections = [];
-
-    // Fixed files: CLAUDE.md + core library files
-    const fixedFiles = [
-        { label: 'CLAUDE.md', path: 'CLAUDE.md' },
-        { label: '.library/index.md', path: '.library/index.md' },
-        { label: '.library/conventions.md', path: '.library/conventions.md' }
-    ];
-
-    for (const file of fixedFiles) {
-        const content = await _readPackageFile(file.path);
-        if (content) {
-            sections.push(`--- ${file.label} ---\n${content}`);
-        }
-    }
-
-    // Auto-discover .md files in each catalog directory
-    for (const dir of _CATALOG_DIRS) {
-        const dirPath = path.join(_packageRoot, '.library', dir);
-        let entries;
-        try {
-            entries = await fs.readdir(dirPath);
-        } catch {
-            logger.debug('help - readLibraryCatalog', `Could not read .library/${dir}/`);
-            continue;
-        }
-
-        const mdFiles = entries.filter((f) => f.endsWith('.md')).sort();
-        for (const file of mdFiles) {
-            const relativePath = `.library/${dir}/${file}`;
-            const content = await _readPackageFile(relativePath);
-            if (content) {
-                sections.push(`--- ${relativePath} ---\n${content}`);
-            }
+    // Fetching delegated to the librarian module; see .library/librarian/
+    try {
+        const result = await librarianFetch(null, { repoRoot: _packageRoot, full: true });
+        if (result.catalog) {
+            logger.debug('help - readLibraryCatalog', 'Catalog loaded via librarian', {
+                files: result.readingList.length,
+                length: result.catalog.length
+            });
         }
-    }
-
-    if (sections.length === 0) {
-        logger.debug('help - readLibraryCatalog', 'No catalog files found');
+        return result.catalog;
+    } catch (err) {
+        logger.debug('help - readLibraryCatalog', 'Librarian fetch failed', {
+            error: err.message
+        });
         return null;
     }
-
-    const catalog = sections.join('\n\n');
-    logger.debug('help - readLibraryCatalog', 'Catalog loaded', {
-        sections: sections.length,
-        length: catalog.length
-    });
-    return catalog;
 };
 
 /**

package/lib/hooks/pre-commit.js

@@ -19,6 +19,7 @@
  * - resolution-prompt: Issue resolution generation
  */
 
+import { join } from 'path';
 import { getStagedFiles, getRepoRoot, getStagedTreeSha } from '../utils/git-operations.js';
 import { writeMarker } from '../utils/hooks-verified-marker.js';
 import { filterFiles } from '../utils/file-operations.js';
@@ -150,6 +151,41 @@ 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);
+                        }
+                    } 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}`);
+                    }
+                    logger.warning('   Run: npm run library:regenerate');
+                }
+            }
+        } catch {
+            logger.warning('📚 Library staleness check unavailable — .library/ tools not found');
+        }
+
         // Step 3: Run linters (fast, deterministic — before Claude analysis)
         // Unfixable lint issues are forwarded to the judge for semantic resolution
         let unfixableLintDetails = [];

package/lib/messages/library-warnings.js

@@ -0,0 +1,29 @@
+/**
+ * File: library-warnings.js
+ * Purpose: Warning wording 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.
+ *
+ * Related tickets:
+ *   AUT-3767 — original placeholder (retired by AUT-3769)
+ *   AUT-3769 — finalized wording + librarian messages module
+ *   AUT-3770 — create-release integration (PR body, label, console)
+ *   AUT-3738 — parent user story
+ */
+
+export {
+    CONSOLE_WARNING_TEMPLATE,
+    PR_BODY_SECTION_TEMPLATE,
+    PR_TAG_VALUE
+} from '../../.library/librarian/messages/staleness-warnings.js';
+
+export const LIBRARY_VERIFY_SKIPPED_WARNING =
+    'Library verification skipped due to an unexpected error. ' +
+    'The version bump will proceed normally.';
+
+export const LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE =
+    'Library verification skipped due to an unexpected error. ' +
+    'The release will proceed normally.';

package/lib/utils/github-api.js

@@ -940,6 +940,36 @@ export const findExistingPR = async ({ owner, repo, head, base }) => {
     }
 };
 
+/**
+ * Update the body of an existing pull request
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number} number - PR number
+ * @param {string} body - New PR body content
+ * @returns {Promise<Object>} Updated PR data
+ */
+export const updatePullRequestBody = async (owner, repo, number, body) => {
+    logger.debug('github-api - updatePullRequestBody', 'Updating PR body', {
+        owner, repo, number, bodyLength: body.length
+    });
+
+    const octokit = getOctokit();
+
+    const { data } = await octokit.pulls.update({
+        owner,
+        repo,
+        pull_number: number,
+        body
+    });
+
+    logger.debug('github-api - updatePullRequestBody', 'PR body updated', {
+        number: data.number,
+        url: data.html_url
+    });
+
+    return data;
+};
+
 /**
  * Get repository information
  * Why: Fetch repo metadata for validation and context

package/lib/utils/linter-runner.js

@@ -45,6 +45,12 @@ export function parseEslintOutput(stdout) {
 
         for (const fileResult of results) {
             for (const msg of fileResult.messages || []) {
+                // Skip ESLint meta-warnings about ignored files — not code quality issues.
+                // Dot-directory files (e.g. .library/) trigger "File ignored by default"
+                // even when ignorePatterns negation is set, because ESLint's default
+                // dot-directory ignore takes precedence for explicitly passed file paths.
+                if (msg.message && msg.message.startsWith('File ignored')) continue;
+
                 const issue = {
                     file: fileResult.filePath || '',
                     line: msg.line,

package/lib/utils/version-manager.js

@@ -377,11 +377,13 @@ export function writeVersionToFile(filePath, type, newVersion) {
 }
 
 /**
- * Updates version in selected files
- * Why: Applies version update to specific VersionFileDescriptor[] subset
+ * Updates version in the given files (resolved mutations from the selector)
+ * Why: Applies version update to the concrete list of files the caller provides.
+ *      Every item in the array is a mutation to apply — the caller is responsible
+ *      for filtering before calling this function.
  *
- * @param {Array} files - Array of VersionFileDescriptor objects with selected=true
- * @param {string} newVersion - New version string
+ * @param {Array} files - Array of VersionFileDescriptor objects to update
+ * @param {string} newVersion - New version string (used when file has no targetVersion)
  */
 export function updateVersionFiles(files, newVersion) {
     logger.debug('version-manager - updateVersionFiles', 'Updating version files', {
@@ -402,10 +404,6 @@ export function updateVersionFiles(files, newVersion) {
     const errors = [];
 
     for (const file of files) {
-        if (!file.selected) {
-            continue; // Skip unselected files
-        }
-
         try {
             // Verify file still exists
             if (!fs.existsSync(file.path)) {