claude-git-hooks 2.45.0 → 2.61.2

package/CLAUDE.md

@@ -1,8 +1,8 @@
-# Repository Context
+# claude-git-hooks
 
-`claude-git-hooks` — intelligent Git hooks system integrating Claude CLI for code analysis, commit message generation, PR creation, and release workflow automation.
+Intelligent Git hooks system integrating Claude CLI for code analysis, commit message generation, PR creation, and release workflow automation.
 
-## Context Acquisition
+## Library
 
 All project knowledge lives in [`.library/`](.library/). Start at [`.library/index.md`](.library/index.md).
 
@@ -10,15 +10,16 @@ Load context based on your current task:
 
 | Task | Load |
 |------|------|
-| Writing or modifying code | [`.library/conventions.md`](.library/conventions.md) — coding standards, testing patterns |
-| Understanding a source module | [`.library/by-code/`](.library/by-code/) — find the book for that file |
-| Understanding a business workflow | [`.library/by-domain/`](.library/by-domain/) — commit pipeline, release management, PR analysis, GitHub integration |
-| Adding a new CLI command | [`.library/by-task-type/add-new-command.md`](.library/by-task-type/add-new-command.md) — 7-book reading sequence |
-| Updating the library after code changes | [`.library/README.md`](.library/README.md) — book schema, template, creation steps |
+| Writing or modifying code | `conventions.md` (Library root) — coding standards, testing patterns |
+| Understanding a source module | `@by-code/` — find the book for that file |
+| Understanding a business workflow | `@by-domain/` — commit pipeline, release management, PR analysis, GitHub integration |
+| Adding a new CLI command | `@by-task-type/add-new-command.md` — 7-book reading sequence |
 
-Books follow a standard template at `.library/templates/book-template.md`. After modifying a module, update its book and the relevant shelf index.
+**Programmatic access**: `fetchLibraryContent(taskOrTopic)` in `.library/librarian/index.js` loads CLAUDE.md + index.md + conventions.md as fixed context, then routes the topic to the relevant index.
 
-## Global Rules
+**Budget-aware loading**: Every index carries `reading_cost_tokens`; task-type sequences split into core vs conditional books. Check token budgets before loading full sequences.
+
+## Rules
 
 These behavioral rules apply to all work in this repository:
 
@@ -31,5 +32,3 @@ These behavioral rules apply to all work in this repository:
 7. **Do NOT use `console.log`** — always use `logger.js`: `info()`, `warning()`, `error()`, `debug()`
 8. **Platform-specific care** — use `path.join()` (no hardcoded `/`); test on Windows, Linux, macOS
 9. **Input sanitization** — use `sanitize.js` for user inputs in shell commands; avoid `shell: true` in `spawn()`
-
-> See [`CLAUDE-MIGRATION.md`](CLAUDE-MIGRATION.md) for a mapping of where each original CLAUDE.md section moved.

package/README.md

@@ -529,6 +529,13 @@ claude-git-hooks/
 │       ├── diff-analysis-orchestrator.js  # Intelligent batch orchestration
 │       ├── judge.js                      # Auto-fix judge (v2.20.0)
 │       └── token-store.js               # Token persistence - settings.local.json
+├── .library/                     # Code Knowledge Library - auto-generated module docs
+│   ├── books/                    # One book per source module (auto + manual sections)
+│   ├── extractor/                # Tree-sitter AST tooling
+│   │   ├── extract.js            # Source → book auto-section generator
+│   │   ├── parser.js             # WASM parser init and grammar loading
+│   │   └── adapters/             # Language-specific CST → normalized AST
+│   └── templates/                # Book schema and category reference
 ├── templates/
 │   ├── pre-commit                # Bash wrapper - invokes Node.js
 │   ├── prepare-commit-msg        # Bash wrapper - invokes Node.js

package/lib/commands/analyze-diff.js

@@ -93,6 +93,33 @@ export async function runAnalyzeDiff(args) {
             console.log(result.testingNotes);
         }
 
+        // Library staleness section
+        try {
+            const { runAll } = 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 staleCount = stalenessResult.stale.length +
+                stalenessResult.orphan_books.length +
+                stalenessResult.unbooked_sources.length;
+            if (staleCount > 0) {
+                console.log('');
+                console.log(`📚 ${colors.yellow}Library Staleness:${colors.reset} ${staleCount} book(s) need attention`);
+                for (const item of stalenessResult.stale) {
+                    console.log(`   └─ stale: ${item.book}`);
+                }
+                for (const item of stalenessResult.orphan_books) {
+                    console.log(`   └─ orphan: ${item.book}`);
+                }
+                for (const src of stalenessResult.unbooked_sources) {
+                    console.log(`   └─ unbooked: ${src}`);
+                }
+                console.log('   Run: npm run library:regenerate');
+            }
+        } catch {
+            logger.warning('📚 Library staleness check unavailable — .library/ tools not found');
+        }
+
         // Save the results in a file with context
         const outputData = {
             prTitle: result.prTitle,

package/lib/commands/back-merge.js

@@ -39,7 +39,8 @@ import {
     checkoutBranch,
     pushBranch,
     deleteRemoteBranch,
-    createCommit
+    createCommit,
+    stageFiles
 } from '../utils/git-operations.js';
 import {
     getLatestLocalTag,
@@ -650,6 +651,53 @@ export async function runBackMerge(args) {
     showSuccess(`✓ Merge committed: ${commitMsg}`);
     console.log('');
 
+    // 14b. Co-change correlation pipeline (AUT-3777)
+    let coChangeReport = null;
+    try {
+        const { coChangePipeline } = await import('../../.library/librarian/index.js');
+
+        showInfo('Running co-change correlation pipeline...');
+        const summary = coChangePipeline({ repoCtx: {} });
+        const { modifiedFiles, perStep, report, warnings, mode } = summary;
+
+        // Surface summary to stdout
+        showInfo(
+            `Co-change: mode=${mode}, detected=${perStep.detection.modifications}, ` +
+            `injected=${perStep.injection.modifications}, warnings=${warnings.length}`
+        );
+        for (const w of warnings) {
+            showWarning(w);
+        }
+
+        // Save report for PR body attachment after push
+        coChangeReport = report;
+
+        if (modifiedFiles.length === 0) {
+            showInfo('Co-change pipeline produced no Library changes');
+        } else {
+            const root = getRepoRoot();
+            const absFiles = modifiedFiles.map(f => path.isAbsolute(f) ? f : path.join(root, f));
+            const stageResult = stageFiles(absFiles);
+
+            if (!stageResult.success) {
+                showWarning(`Failed to stage co-change files: ${stageResult.error}`);
+            } else {
+                const windowDesc = tagName ? `${tagName}..HEAD` : 'full history';
+                const libCommitMsg = `chore(library): co-change correlations for ${windowDesc}`;
+                const libCommit = createCommit(libCommitMsg);
+
+                if (!libCommit.success) {
+                    showWarning(`Failed to commit co-change files: ${libCommit.error}`);
+                } else {
+                    showSuccess(`Co-change committed: ${libCommitMsg} (${modifiedFiles.length} file(s))`);
+                }
+            }
+        }
+    } catch (err) {
+        logger.warning(`co-change pipeline skipped: ${err.message}`);
+        logger.debug('back-merge', 'Co-change pipeline skipped', { error: err.message });
+    }
+
     // 15. Verify sync
     try {
         const postMergeDivergence = getDivergence(opts.into, `origin/${opts.from}`);
@@ -719,6 +767,52 @@ export async function runBackMerge(args) {
         await _revertFollowup(rcBranchForLog, repoRoot);
     }
 
+    // 18b. Attach co-change report to PR body (AUT-3777)
+    if (coChangeReport && pushStatus === 'pushed') {
+        try {
+            const { parseGitHubRepo } = await import('../utils/github-client.js');
+            const { findExistingPR, updatePullRequestBody } = await import('../utils/github-api.js');
+            const repoInfo = parseGitHubRepo();
+
+            const existingPR = await findExistingPR({
+                owner: repoInfo.owner,
+                repo: repoInfo.repo,
+                head: opts.from,
+                base: opts.into,
+            });
+
+            if (existingPR) {
+                const OPEN_MARKER = '<!-- LIBRARY_COCHANGE_REPORT -->';
+                const CLOSE_MARKER = '<!-- /LIBRARY_COCHANGE_REPORT -->';
+                const section = `${OPEN_MARKER}\n${coChangeReport}\n${CLOSE_MARKER}`;
+                const markerRegex = new RegExp(
+                    `${OPEN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${CLOSE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`
+                );
+
+                let newBody;
+                if (markerRegex.test(existingPR.body || '')) {
+                    // Re-run: replace existing section
+                    newBody = (existingPR.body).replace(markerRegex, section);
+                } else {
+                    // First run: append section
+                    newBody = `${existingPR.body || ''}\n\n${section}`;
+                }
+
+                await updatePullRequestBody(repoInfo.owner, repoInfo.repo, existingPR.number, newBody);
+                showSuccess('Co-change report attached to PR body');
+            } else {
+                logger.debug('back-merge', 'No existing PR found for report attachment', {
+                    head: opts.from,
+                    base: opts.into,
+                });
+            }
+        } catch (prErr) {
+            logger.debug('back-merge', 'Could not attach co-change report to PR', {
+                error: prErr.message,
+            });
+        }
+    }
+
     // 19. Summary
     console.log('');
     console.log(`${colors.green}═════════════════════════════════════════════════${colors.reset}`);

package/lib/commands/bump-version.js

@@ -54,6 +54,10 @@ import {
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { colors, error, checkGitRepo } from './helpers.js';
+import {
+    CONSOLE_WARNING_TEMPLATE,
+    LIBRARY_VERIFY_SKIPPED_WARNING
+} from '../messages/library-warnings.js';
 
 /**
  * Validates prerequisites before version bump
@@ -374,6 +378,25 @@ function restoreSnapshot(snapshot) {
     });
 }
 
+/**
+ * Emit a loud Library staleness warning to stderr.
+ * Content comes from the wording constant + 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: 'deferred' });
+
+    const lines = ['', bar, '', `${y}${content}${r}`, '', bar, ''];
+
+    process.stderr.write(lines.join('\n'));
+}
+
 /**
  * Bump version command
  * @param {Array<string>} args - Command arguments
@@ -441,6 +464,22 @@ export async function runBumpVersion(args) {
 
     showSuccess('Prerequisites validated');
 
+    // Library verification gate — silent on clean, loud-warn on stale, never-hard-fail
+    logger.debug('bump-version', 'Running Library verification gate');
+    try {
+        const { verify } = await import('../../.library/librarian/index.js');
+        const verifyResult = await verify();
+
+        if (verifyResult.clean) {
+            logger.debug('bump-version', 'Library is clean — no warning needed');
+        } else {
+            _emitLibraryWarning(verifyResult);
+        }
+    } catch (verifyErr) {
+        const msg = `\n${colors.yellow}  ${LIBRARY_VERIFY_SKIPPED_WARNING} ${verifyErr.message}${colors.reset}\n\n`;
+        process.stderr.write(msg);
+    }
+
     // Step 2: Discover all version files
     logger.debug('bump-version', 'Step 2: Discovering version files');
     const discovery = discoverVersionFiles();

package/lib/commands/close-release.js

@@ -356,6 +356,28 @@ 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);
+            }
+            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 ─────────────────────────────
 
         showInfo('Resetting to origin/main (--soft)...');

package/lib/commands/create-pr.js

@@ -22,7 +22,7 @@ import {
     showWarning,
     promptConfirmation
 } from '../utils/interactive-ui.js';
-import { getBranchPushStatus, pushBranch } from '../utils/git-operations.js';
+import { getBranchPushStatus, pushBranch, stageFiles, createCommit, getRepoRoot } from '../utils/git-operations.js';
 import logger from '../utils/logger.js';
 import { resolveLabels } from '../utils/label-resolver.js';
 import { CostTracker } from '../utils/cost-tracker.js';
@@ -664,6 +664,78 @@ export async function runCreatePr(args) {
             logger.debug('create-pr', 'No unpushed tags found, continuing');
         }
 
+        // Step 5.8: Library maintenance pipeline (AUT-3764)
+        logger.debug('create-pr', 'Step 5.8: Running Library maintenance pipeline');
+        try {
+            showInfo('Running Library maintenance pipeline...');
+            const { createPrPipeline } = await import('../../.library/librarian/index.js');
+            const root = getRepoRoot();
+
+            const pipelineSummary = await createPrPipeline({ repoRoot: root });
+            const {
+                modifiedFiles: libraryFiles,
+                perStep,
+                pendingDueToApiDown,
+                warnings: pipelineWarnings,
+            } = pipelineSummary;
+
+            // Surface pipeline summary
+            logger.debug('create-pr', 'Pipeline completed', {
+                modifiedCount: libraryFiles.length,
+                pendingDueToApiDown,
+                warningCount: pipelineWarnings.length,
+            });
+            showInfo(`Staleness: ${perStep.staleness.staleCount} stale, ${perStep.staleness.unbookedCount} unbooked`);
+            if (perStep.regen.changed > 0) {
+                showInfo(`Regenerated: ${perStep.regen.changed} book(s)`);
+            }
+            if (perStep.addRemoveRename.created > 0) {
+                showInfo(`Created: ${perStep.addRemoveRename.created} new book(s)`);
+            }
+            if (pendingDueToApiDown > 0) {
+                showWarning(`Gotchas pending (API down): ${pendingDueToApiDown}`);
+            }
+            for (const w of pipelineWarnings) {
+                showWarning(w);
+            }
+
+            if (libraryFiles.length === 0) {
+                showInfo('Library already in sync');
+            } else {
+                // Stage all modified Library files (stageFiles expects absolute paths)
+                const absFiles = libraryFiles.map(f => path.join(root, f));
+                const stageResult = stageFiles(absFiles);
+
+                if (!stageResult.success) {
+                    showWarning(`Failed to stage Library files: ${stageResult.error}`);
+                } else {
+                    // Commit with deterministic message — separate commit, not amend
+                    const libraryCommitMsg = `chore(library): sync books for ${currentBranch}`;
+                    const commitResult = createCommit(libraryCommitMsg);
+
+                    if (!commitResult.success) {
+                        showWarning(`Failed to commit Library changes: ${commitResult.error}`);
+                    } else {
+                        showSuccess(`Library committed: ${libraryCommitMsg} (${libraryFiles.length} file(s))`);
+
+                        // Push the Library commit to the PR branch's remote
+                        const libraryPushResult = pushBranch(currentBranch);
+                        if (!libraryPushResult.success) {
+                            showWarning(`Failed to push Library commit: ${libraryPushResult.error}`);
+                        } else {
+                            showSuccess('Library commit pushed');
+                        }
+                    }
+                }
+            }
+        } catch (pipelineErr) {
+            // Pipeline failure is non-blocking — log and continue with PR creation
+            logger.warning('create-pr', 'Library pipeline failed, continuing', {
+                error: pipelineErr.message,
+            });
+            showWarning(`Library pipeline unavailable: ${pipelineErr.message}`);
+        }
+
         // Step 6: Generate PR metadata using engine
         logger.debug('create-pr', 'Step 6: Generating PR metadata with engine');
         showInfo('Generating PR metadata with Claude...');