claude-git-hooks 2.61.2 → 2.66.1

package/CHANGELOG.md

@@ -5,45 +5,283 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.66.1] - 2026-06-10
+
+### 🐛 Fixed
+- Normalized path separators to forward slashes in staleness checker for cross-platform compatibility
+
+
+## [2.66.0] - 2026-06-10
+
+### ✨ Added
+- Multi-language extractor registry with pluggable per-language architecture [AUT-3742]
+- End-to-end SDLC stability check test suite
+- Version alignment validation now scoped to base branch tags (#185)
+- Extractor notes template for documenting per-language extractors
+
+### 🔧 Changed
+- Moved arrow-function extraction from monolithic extractor to pluggable extractor module [AUT-3742]
+- Decoupled `lib/` from `.library/` static imports with ESLint enforcement rule [AUT-3742]
+- Library maintenance pipeline now runs before tag push in `create-pr`, ensuring library books are included in tagged commits
+- Simplified `bump-version` interactive file selection to direct toggle list, removing multi-choice menu
+- Tags are force-repointed to HEAD after library commit so tagged version includes regenerated books
+
+### 🐛 Fixed
+- Fixed `create-pr` gotcha solicitation receiving empty file paths instead of actual book content (#190)
+- Fixed `create-pr` tag comparison using global tag list instead of base branch scope
+- Fixed `create-pr` library pipeline leaking host-repo paths into foreign repositories (#186)
+- Fixed `bump-version` crashing on non-semver version files such as Maven `${revision}` placeholders (#187)
+- Fixed version tag lookup scanning all branches instead of only the HEAD branch (#185)
+- Fixed stale git worktree leftovers causing integration test failures
+
+### 🗑️ Removed
+- Removed per-file custom version entry option (`promptEditField`) from `bump-version` interactive selection
+
+
+## [2.65.0] - 2026-06-08
+
+### ✨ Added
+- Multi-language extractor registry with pluggable per-language extractors (AUT-3742)
+- Extractor interface contract and runtime validator for language extractor plugins (AUT-3742)
+- JS extractor notes template for documenting new extractors (AUT-3742)
+- Test harness with JS fixtures for extractor validation (AUT-3742)
+- Version alignment now scoped to base branch tags instead of global tag lookup
+
+### 🔧 Changed
+- Arrow-function extraction moved from monolithic extract.js to pluggable JS extractor module (AUT-3742)
+- Decoupled lib/ from .library/ static imports with ESLint enforcement — lib/ must use dynamic import() for Library integration (AUT-3742)
+- Library maintenance pipeline in create-pr now runs before tag push so tags include regenerated books
+- Unpushed tags are force-repointed to HEAD after library commit to include book changes
+- Gotcha solicitation now receives full book content instead of just file paths
+- bump-version interactive file selection simplified — goes directly to toggle list, non-semver files pre-deselected
+
+### 🐛 Fixed
+- Fixed create-pr library pipeline running incorrectly in foreign repos by deriving paths from resolver config (#186)
+- Fixed bump-version crash when non-semver files (e.g., Maven `${revision}`) reached version parser (#187)
+- Fixed create-pr comparing tags against global scope instead of base branch (#185, #189)
+- Fixed create-pr using stale tag reference after library pipeline commit
+- Fixed local tag lookup not scoped to HEAD branch, causing cross-branch version mismatches
+
+### 🗑️ Removed
+- Removed per-file custom version editing (option `e`) from bump-version interactive selection
+- Removed `promptMenu` and `promptEditField` usage from bump-version flow
+
+
+## [2.64.4] - 2026-06-08
+
+### ✨ Added
+- Added multi-language extractor registry with pluggable architecture and runtime interface validation (AUT-3742, #184)
+- Added JS extractor as first pluggable extractor with dedicated test harness and fixtures (AUT-3742)
+- Added extractor notes template for documenting per-language extractors (AUT-3742)
+- Added branch-scoped tag lookup functions `getLatestLocalTagOnBranch()` and `getLatestRemoteTagOnBranch()` to git-tag-manager (#185)
+- Added branch-scoped version alignment validation in `create-pr` (#185)
+
+### 🔧 Changed
+- Decoupled `lib/` from `.library/` static imports with ESLint restricted-imports guard (AUT-3742)
+- Moved arrow-function extraction from monolithic extractor into pluggable JS extractor module (AUT-3742)
+- Simplified `bump-version` interactive file selection — removed menu, goes directly to toggle list with non-semver files pre-deselected (#187)
+- Library pipeline in `create-pr` now derives paths from resolver config, preventing git-hooks paths from leaking into foreign repos (#186)
+- Reordered `create-pr` steps so library pipeline runs before tag push, then re-points unpushed tags to HEAD to include library commits
+
+### 🐛 Fixed
+- Fixed `bump-version` crash when non-semver files (e.g., Maven `${revision}`) were included in version resolution (#187)
+- Fixed `create-pr` library pipeline using hardcoded paths that broke in foreign repositories (#186)
+- Fixed version alignment and tag lookup returning results from unrelated branches instead of scoping to base branch (#185)
+- Fixed `create-pr` tag becoming stale after library book regeneration by running the pipeline before tag push and re-pointing tags
+
+### 🗑️ Removed
+- Removed `promptMenu` and `promptEditField` options from `bump-version` interactive file selection (#187)
+
+
+## [2.64.3] - 2026-06-08
+
+### ✨ Added
+- Added multi-language extractor registry with pluggable interface, including JS extractor and notes template (AUT-3742)
+- Added library maintenance pipeline step in create-pr that regenerates books before tag push
+- Added branch-scoped tag lookup functions (`getLatestLocalTagOnBranch`, `getLatestRemoteTagOnBranch`) to git-tag-manager
+- Added ESLint rule preventing `lib/` from statically importing `.library/` modules (AUT-3742)
+- Added extractor test harness with JS fixtures (AUT-3742)
+
+### 🔧 Changed
+- Moved arrow-function extraction from monolithic `extract.js` into pluggable extractor under `librarian/extractors/registered/js/` (AUT-3742)
+- Scoped version alignment validation to base branch tags instead of global tag lookup
+- Simplified bump-version interactive file selection — goes directly to toggle list, non-semver files pre-deselected
+- Library pipeline now derives booksDir/sourceDir from resolver config when repoRoot is overridden, preventing path leakage into foreign repos
+- Unpushed tags are force-repointed to HEAD after library commit so tags include regenerated books
+
+### 🐛 Fixed
+- Fixed create-pr using stale tag for comparison after library regeneration created a new commit
+- Fixed create-pr running library pipeline in foreign repos where `.library/` paths were invalid (#186)
+- Fixed bump-version crashing on non-semver version files (e.g., Maven `${revision}`) by excluding them from version resolution (#187)
+- Fixed local tag lookup scanning tags from all branches instead of only the current HEAD branch (#185)
+
+### 🗑️ Removed
+- Removed per-file custom version editing (`promptEditField` option) from bump-version interactive selection
+- Removed `promptMenu` four-option flow from bump-version in favor of direct toggle list
+
+
+## [2.64.2] - 2026-06-08
+
+### ✨ Added
+- Multi-language extractor registry with pluggable extractor interface and JS extractor (AUT-3742, #184)
+- Extractor notes template and per-extractor documentation standard (AUT-3742)
+- Test harness for extractors with JS fixtures (AUT-3742)
+- ESLint rule preventing lib/ from statically importing .library/ modules (AUT-3742)
+- Version alignment now scoped to base branch tags for accurate cross-branch comparisons (#185)
+- Library maintenance pipeline step in create-pr to regenerate books before tagging (#187)
+
+### 🔧 Changed
+- Moved arrow-function extraction from monolithic extractor to pluggable JS extractor module (AUT-3742)
+- Decoupled lib/ from .library/ imports — library integration now uses dynamic import with graceful degradation (AUT-3742)
+- Library pipeline in create-pr derives paths from resolver.yaml config instead of hardcoded values (#186)
+- Simplified bump-version interactive file selection to use toggle list directly, removing menu options (a/s/e/c) (#187)
+- Tags are re-pointed to HEAD after library commit so tagged releases include regenerated books (#187)
+
+### 🐛 Fixed
+- Fixed bump-version crashing on non-semver version files (e.g., Maven `${revision}`) by excluding them from version resolution (#187)
+- Fixed create-pr library pipeline leaking git-hooks paths into foreign repos (#186)
+- Fixed local tag lookup scanning all branches instead of scoping to HEAD branch (#185)
+- Fixed stale tags in create-pr when library pipeline generates a new commit after tag creation (#187)
+
+### 🗑️ Removed
+- Removed per-file custom version editing (option `e`) from bump-version interactive selection (#187)
+
+
+## [2.64.1] - 2026-06-08
+
+### ✨ Added
+- Multi-language extractor registry with pluggable architecture for Library book generation [AUT-3742] (#184)
+- JS extractor as first pluggable extractor with Tree-sitter parsing, extractor notes template, and test harness [AUT-3742] (#184)
+- ESLint rule preventing `lib/` from statically importing `.library/` modules [AUT-3742] (#184)
+- Branch-scoped tag lookup functions `getLatestLocalTagOnBranch()` and `getLatestRemoteTagOnBranch()` in git-tag-manager (#185)
+
+### 🔧 Changed
+- Library pipeline (`createPrPipeline`) now derives `booksDir`/`sourceDir` from overridden `repoRoot`, preventing git-hooks paths from leaking into foreign repos (#186)
+- Version alignment scoped to base branch tags instead of global tag list (#185)
+- Bump-version interactive file selection simplified to direct toggle list with non-semver files pre-deselected
+- Moved arrow-function extraction from monolithic `extract.js` to pluggable extractor module [AUT-3742]
+
+### 🐛 Fixed
+- Excluded non-semver files (e.g., Maven `${revision}`) from version resolution in bump-version command, preventing `parseVersion()` failures
+- Fixed library pipeline using hardcoded git-hooks paths when running in foreign repos (#186)
+- Scoped local tag lookup to HEAD branch to avoid cross-branch version pollution (#185)
+
+### 🗑️ Removed
+- Removed menu-based file selection (all/select/edit/cancel) from bump-version in favor of direct toggle list
+- Removed per-file custom version entry (`targetVersion`) from interactive file selection
+
+
+## [2.64.0] - 2026-06-08
+
+### ✨ Added
+- Multi-language extractor registry with pluggable interface and JS extractor (AUT-3742)
+- Extractor notes template for documenting per-language extractors (AUT-3742)
+- Test harness with JS fixtures for extractor validation (AUT-3742)
+- Branch-scoped tag lookup methods `getLatestLocalTagOnBranch()` and `getLatestRemoteTagOnBranch()` in git-tag-manager
+- ESLint `no-restricted-imports` rule preventing `lib/` from statically importing `.library/` modules (AUT-3742)
+
+### 🔧 Changed
+- Moved arrow-function extraction from monolithic `extract.js` to pluggable extractor module under `librarian/extractors/registered/js/` (AUT-3742)
+- `validateVersionAlignment()` now accepts a `baseBranch` parameter, scoping version checks to the relevant branch tags instead of all tags
+- Library pipeline (`createPrPipeline`) now derives `booksDir`/`sourceDir` from resolver config when `repoRoot` is overridden, preventing path leakage into foreign repos
+
+### 🐛 Fixed
+- Fixed local tag lookup returning tags from unrelated branches instead of scoping to HEAD branch
+- Fixed library pipeline leaking git-hooks internal paths into foreign repos during PR creation (#185)
+
+
+## [2.63.1] - 2026-06-03
+
+### ✨ Added
+
+- Multi-language extractor registry with pluggable interface and runtime validation (AUT-3742, #184)
+- JS extractor as first pluggable extractor with full EXTRACTOR_NOTES documentation (AUT-3742)
+- Extractor notes template for documenting new language extractors (AUT-3742)
+- Test harness with JS fixtures for extractor validation (AUT-3742)
+- Version alignment scoped to base branch tags for accurate cross-branch versioning
+
+### 🔧 Changed
+
+- Decoupled lib/ from .library/ imports with ESLint no-restricted-imports rule to enforce package boundary (AUT-3742)
+- Refactored arrow-function extraction from monolithic extract.js into pluggable JS extractor module (AUT-3742)
+
+### 🐛 Fixed
+
+- Scoped local tag lookup to HEAD branch to prevent cross-branch version conflicts
+
+## [2.63.0] - 2026-06-03
+
+### ✨ Added
+
+- Added multi-language extractor registry with convention-driven loader, priority-based lookup, and warn-and-skip error handling (AUT-3742)
+- Added Extractor interface definition with JSDoc types and runtime validator for pluggable per-language extractors (AUT-3742)
+- Added JS/ESM pluggable extractor conforming to the new Extractor interface (AUT-3742)
+- Added extractor notes template and canonical JS extractor documentation covering supported constructs, known limitations, and test fixtures (AUT-3742)
+- Added ESLint `no-restricted-imports` rule preventing `lib/` from statically importing `.library/` modules (AUT-3742)
+- Added extractor test harness with JS fixtures for eight construct categories (AUT-3742)
+
+### 🔧 Changed
+
+- Refactored arrow-function extraction from monolithic `extract.js` into standalone pluggable extractor module under `librarian/extractors/registered/js/` (AUT-3742)
+- Decoupled `lib/` source code from `.library/` imports — runtime integration now requires dynamic `import()` with graceful degradation (AUT-3742)
+
+## [2.62.0] - 2026-06-02
+
+### ✨ Added
+
+- Added structure detector pipeline for Library bootstrap — 3-stage detection (filesystem scan → Haiku inference → interactive console) that generates `.library/structure.yaml` config (AUT-3741)
+- Added deterministic filesystem scanner with configurable depth/child limits, BOM file detection, and language-by-layer counting (AUT-3741)
+- Added Haiku-based structure inference with exponential-backoff retry, scanner-detected language reconciliation, and graceful degradation to stub config on API failure (AUT-3741)
+- Added interactive 3-option console flow (Accept / Reject / Retry) with re-run safety supporting Keep / Overwrite / Merge of existing configs (AUT-3741)
+- Added structure detector documentation to Library README including sequence diagram, consumer contract, config format, and worked example (AUT-3741)
+
+### 🐛 Fixed
+
+- Fixed tag staleness during Library regeneration (#179)
+
 ## [2.61.2] - 2026-06-01
 
 ### 🐛 Fixed
-- Fixed incorrect import path for gotcha solicitation in PR pipeline
 
+- Fixed incorrect import path for gotcha solicitation in PR pipeline
 
 ## [2.61.1] - 2026-06-01
 
 ### ✨ Added
+
 - Auto-regeneration of stale Library books during `create-release` — stale books are now regenerated before the release is tagged, keeping the tag accurate (#178, AUT-3738)
 
 ### 🔧 Changed
+
 - Staleness warning templates are now context-aware: `CONSOLE_WARNING_TEMPLATE` and `PR_BODY_SECTION_TEMPLATE` accept an `autoRegen` option to tailor messaging per consumer (`will-run` for create-release, `deferred` for bump-version, `completed`/`failed` in PR body)
 - PR body staleness section now reflects the actual auto-regeneration outcome instead of always listing remediation scripts
 - Console staleness warning in `bump-version` now tells the user that Library will be auto-regenerated when they run `create-pr`
 
 ### 🗑️ Removed
-- Removed static recommended-scripts list from console staleness warnings (replaced by context-aware auto-regeneration messages)
 
+- Removed static recommended-scripts list from console staleness warnings (replaced by context-aware auto-regeneration messages)
 
 ## [2.61.0] - 2026-06-01
 
 ### ✨ Added
+
 - Added canonical staleness-warning templates (`CONSOLE_WARNING_TEMPLATE`, `PR_BODY_SECTION_TEMPLATE`, `PR_TAG_VALUE`) for consistent Library staleness messaging across all consumer commands (AUT-3738)
 - Added non-blocking Library staleness verification gate to the `create-release` workflow — warns operators when Library books are out of date without blocking the release (AUT-3738)
 - Added automatic release PR creation step in `create-release` with idempotency check, staleness section in PR body wrapped in marker comments, and `library-stale` label when applicable (AUT-3738)
 - Added `LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE` constant for release-specific Library verification skip messaging (AUT-3738)
 
 ### 🔧 Changed
+
 - Refactored `bump-version` Library warning to use the canonical `CONSOLE_WARNING_TEMPLATE` instead of inline formatting (AUT-3738)
 - Changed `create-release` Library staleness gate from blocking (exit on stale) to non-blocking (warn and continue), using the librarian `verify()` API instead of raw staleness tools (AUT-3738)
 - Refactored `library-warnings.js` to re-export canonical wording from the librarian messages module instead of defining constants inline (AUT-3738)
 - Updated Library books for `create-release`, `bump-version`, and `library-warnings` to reflect new dependencies and exports (AUT-3738)
 
 ### 🗑️ Removed
+
 - Removed blocking Library staleness check from `create-release` that imported `.library/tools/staleness.js` directly and aborted on drift (AUT-3738)
 - Removed `LIBRARY_STALE_WARNING` constant from `library-warnings.js`, replaced by canonical `CONSOLE_WARNING_TEMPLATE` (AUT-3738)
 
-
 ## [2.61.0] - 2026-05-29
 
 ### ✨ Added

package/lib/commands/bump-version.js

@@ -48,9 +48,7 @@ import {
     showError,
     showWarning,
     promptConfirmation,
-    promptMenu,
-    promptToggleList,
-    promptEditField
+    promptToggleList
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { colors, error, checkGitRepo } from './helpers.js';
@@ -209,7 +207,9 @@ function displayDiscoveryTable(discovery) {
     );
     console.log('');
 
-    if (discovery.files.length === 0) {
+    const visibleFiles = discovery.files.filter((f) => f.selected);
+
+    if (visibleFiles.length === 0) {
         console.log('  No version files found.');
         console.log('');
         return;
@@ -221,8 +221,8 @@ function displayDiscoveryTable(discovery) {
     );
     console.log(`  ${'-'.repeat(3)} ${'-'.repeat(35)} ${'-'.repeat(15)} ${'-'.repeat(15)}`);
 
-    // Table rows
-    discovery.files.forEach((file, index) => {
+    // Table rows (only semver files)
+    visibleFiles.forEach((file, index) => {
         const num = `${index + 1}`.padEnd(3);
         const filePath = file.relativePath.padEnd(35);
         const fileType = file.projectLabel.padEnd(15);
@@ -293,70 +293,20 @@ function showDryRunPreview(info) {
  */
 async function promptFileSelection(discovery) {
     console.log('');
-    showWarning('Version mismatch detected or interactive mode enabled');
-    console.log('');
-
-    const options = [
-        { key: 'a', label: 'Update all files' },
-        { key: 's', label: 'Select which files to update' },
-        { key: 'e', label: 'Edit version per file (advanced)' },
-        { key: 'c', label: 'Cancel' }
-    ];
-
-    const choice = await promptMenu('Choose action:', options, 'a');
-
-    if (choice === 'c') {
-        showInfo('Version bump cancelled');
-        process.exit(0);
-    }
 
-    if (choice === 'a') {
-        // All files selected
-        return discovery.files;
-    }
-
-    if (choice === 's') {
-        // Toggle list selection
-        const items = discovery.files.map((file, index) => ({
-            key: `${index}`,
-            label: `${file.relativePath} (${file.projectLabel}) - ${file.version || 'N/A'}`,
-            selected: file.selected
-        }));
-
-        const selectedKeys = await promptToggleList(
-            'Select files to update (type number to toggle, Enter to confirm):',
-            items
-        );
-
-        // Filter files by selected keys
-        return discovery.files.filter((_, index) => selectedKeys.includes(`${index}`));
-    }
-
-    if (choice === 'e') {
-        // Per-file version editing
-        showInfo('Enter target version for each file (press Enter to keep calculated version)');
-        console.log('');
-
-        for (const file of discovery.files) {
-            const input = await promptEditField(
-                `${file.relativePath} (${file.projectLabel})`,
-                file.version || 'N/A'
-            );
+    const semverFiles = discovery.files.filter((f) => f.selected);
+    const items = semverFiles.map((file, index) => ({
+        key: `${index}`,
+        label: `${file.relativePath} (${file.projectLabel}) - ${file.version || 'N/A'}`,
+        selected: true
+    }));
 
-            // If user entered something different from current version, store it
-            if (input !== file.version && input !== 'N/A') {
-                if (!validateVersionFormat(input)) {
-                    showWarning(`Invalid version format: ${input} — skipping ${file.relativePath}`);
-                    continue;
-                }
-                file.targetVersion = input;
-            }
-        }
-
-        return discovery.files;
-    }
+    const selectedKeys = await promptToggleList(
+        'Select files to update (type number to toggle, Enter to confirm):',
+        items
+    );
 
-    return discovery.files;
+    return semverFiles.filter((_, index) => selectedKeys.includes(`${index}`));
 }
 
 /**
@@ -504,15 +454,6 @@ export async function runBumpVersion(args) {
     // Display discovery table
     displayDiscoveryTable(discovery);
 
-    const currentVersion = discovery.resolvedVersion;
-
-    if (!currentVersion) {
-        showError('Could not determine current version from discovered files');
-        process.exit(1);
-    }
-
-    showInfo(`Current version: ${currentVersion}`);
-
     // Step 3: File selection (if mismatch or interactive mode)
     let selectedFiles = discovery.files.filter((f) => f.selected);
 
@@ -528,6 +469,22 @@ export async function runBumpVersion(args) {
         console.log('');
     }
 
+    // Derive current version from selected files (not from discovery.resolvedVersion)
+    const selectedVersions = selectedFiles
+        .filter((f) => f.version !== null)
+        .map((f) => f.version);
+    const uniqueSelected = [...new Set(selectedVersions)];
+    const currentVersion = uniqueSelected.length === 1
+        ? uniqueSelected[0]
+        : discovery.resolvedVersion;
+
+    if (!currentVersion || !validateVersionFormat(currentVersion)) {
+        showError('Could not determine a valid semver version from selected files');
+        process.exit(1);
+    }
+
+    showInfo(`Current version: ${currentVersion}`);
+
     // Step 4: Calculate new version or apply suffix operation
     logger.debug('bump-version', 'Step 4: Calculating new version');
     let newVersion;

package/lib/commands/create-pr.js

@@ -364,7 +364,7 @@ export async function runCreatePr(args) {
         // Step 5.6: Version alignment validation (Issue #44)
         logger.debug('create-pr', 'Step 5.6: Validating version alignment');
         const { validateVersionAlignment } = await import('../utils/version-manager.js');
-        const versionCheck = await validateVersionAlignment();
+        const versionCheck = await validateVersionAlignment(baseBranch);
 
         if (!versionCheck.aligned) {
             showWarning('Version misalignment detected:');
@@ -451,23 +451,135 @@ export async function runCreatePr(args) {
             }
         }
 
-        // Step 5.7: Smart tag pushing (Issue #44)
-        logger.debug('create-pr', 'Step 5.7: Checking and pushing unpushed tags');
+        // Step 5.7: Library maintenance pipeline (AUT-3764)
+        // Runs BEFORE tag push so that library regen is included in the tagged commit.
+        // Guard: only run if the current repo has its own .library/ setup.
+        // When claude-hooks is installed in a foreign repo (npm link / file: ref),
+        // the relative import resolves to git-hooks' .library/ — not this repo's.
+        let libraryCommitted = false;
+        const root = getRepoRoot();
+        const libraryResolverPath = path.join(root, '.library', 'resolver.yaml');
+        if (!fs.existsSync(libraryResolverPath)) {
+            logger.debug('create-pr', 'No .library/resolver.yaml in current repo — skipping Library pipeline');
+        } else {
+            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 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 {
+                            libraryCommitted = true;
+                            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 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');
         const {
             compareLocalAndRemoteTags,
             pushTags: pushTagsUtil,
-            getLatestLocalTag,
-            getLatestRemoteTag,
+            createTag: createTagUtil,
+            getLatestRemoteTagOnBranch,
             parseTagVersion
         } = await import('../utils/git-tag-manager.js');
         const { compareVersions } = await import('../utils/version-manager.js');
 
+        // If library was committed after bump-version created the tag,
+        // re-point unpushed tags to HEAD so the tag includes library books.
+        if (libraryCommitted) {
+            const unpushedTags = await compareLocalAndRemoteTags();
+            for (const tag of unpushedTags.localNewer) {
+                const version = parseTagVersion(tag);
+                if (version) {
+                    logger.debug('create-pr', 'Re-pointing tag to include library commit', { tag });
+                    let origTagMsg = '';
+                    try { origTagMsg = execSync(`git tag -l --format="%(contents)" ${tag}`, { encoding: 'utf8' }).trim(); } catch { /* ignore */ }
+                    const tagMsg = origTagMsg || `Release version ${version}`;
+                    try {
+                        await createTagUtil(version, tagMsg, { force: true });
+                        showInfo(`Tag ${tag} moved to include library commit`);
+                    } catch (tagErr) {
+                        logger.warning('create-pr', 'Failed to re-point tag, continuing', { tag, error: tagErr.message });
+                    }
+                }
+            }
+        }
+
         const tagComparison = await compareLocalAndRemoteTags();
 
         if (tagComparison.localNewer.length > 0) {
-            // Get latest local and remote tags for comparison
-            const latestLocalTag = getLatestLocalTag();
-            const latestRemoteTag = await getLatestRemoteTag();
+            // Derive latest unpushed tag (scoped to what's actually being pushed)
+            const sortedUnpushed = tagComparison.localNewer
+                .map((t) => ({ tag: t, version: parseTagVersion(t) }))
+                .filter((t) => t.version !== null)
+                .sort((a, b) => compareVersions(a.version, b.version));
+            const latestLocalTag = sortedUnpushed.length > 0
+                ? sortedUnpushed[sortedUnpushed.length - 1].tag
+                : tagComparison.localNewer[0];
+            // Compare against latest remote tag on the BASE branch (not global latest)
+            const latestRemoteTag = getLatestRemoteTagOnBranch(baseBranch);
 
             const localVersion = latestLocalTag ? parseTagVersion(latestLocalTag) : null;
             const remoteVersion = latestRemoteTag ? parseTagVersion(latestRemoteTag) : null;
@@ -483,7 +595,7 @@ export async function runCreatePr(args) {
             let shouldPushTags = false;
             let userChoice = null;
 
-            // Case 1: Local tag > Remote tag → Auto-push
+            // Case 1: Local tag > Remote tag → Auto-push (normal bump-version flow)
             if (localVersion && remoteVersion && compareVersions(localVersion, remoteVersion) > 0) {
                 logger.debug('create-pr', 'Local version > remote version, auto-pushing', {
                     localVersion,
@@ -494,7 +606,7 @@ export async function runCreatePr(args) {
                 showInfo('Auto-pushing tag to remote...');
                 shouldPushTags = true;
 
-                // Case 2: Local tag = Remote tag → Prompt with warning
+                // Case 2: Local tag = Remote tag → Prompt with warning (may already be pushed)
             } else if (
                 localVersion &&
                 remoteVersion &&
@@ -534,7 +646,7 @@ export async function runCreatePr(args) {
                     shouldPushTags = true;
                 }
 
-                // Case 3: Local tag < Remote tag → Prompt with error
+                // Case 3: Local tag < Remote tag → Prompt with warning (someone pushed newer)
             } else if (
                 localVersion &&
                 remoteVersion &&
@@ -664,78 +776,6 @@ 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...');

package/lib/commands/help.js

@@ -18,8 +18,6 @@ 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
  * Why: AI help must always fetch from the tool's own repo, not the user's current repo
@@ -192,10 +190,22 @@ const _readPackageFile = async (relativePath) => {
  * Why: The catalog provides navigational context for the AI librarian (Pass 1).
  * Delegates to the librarian module for directory discovery and routing.
  *
+ * Uses dynamic import() because .library/ is not shipped in the npm package —
+ * it only exists in the source repo. When running from a global install,
+ * the import fails gracefully and the help command falls back to static help.
+ *
  * @returns {Promise<string|null>} Concatenated catalog or null if nothing could be read
  */
 const readLibraryCatalog = async () => {
-    // Fetching delegated to the librarian module; see .library/librarian/
+    let librarianFetch;
+    try {
+        const mod = await import('../../.library/librarian/index.js');
+        librarianFetch = mod.fetchLibraryContent;
+    } catch {
+        logger.debug('help - readLibraryCatalog', 'Library not available (expected in global install)');
+        return null;
+    }
+
     try {
         const result = await librarianFetch(null, { repoRoot: _packageRoot, full: true });
         if (result.catalog) {

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

@@ -248,13 +248,14 @@ export function discoverVersionFiles(options = {}) {
                 const registry = VERSION_FILE_TYPES[fileType];
                 if (registry && entry.name === registry.filename) {
                     const version = registry.readVersion(fullPath);
+                    const isSemver = version !== null && validateVersionFormat(version);
                     const descriptor = {
                         path: fullPath,
                         relativePath: path.relative(repoRoot, fullPath),
                         type: fileType,
                         projectLabel: registry.projectLabel,
                         version,
-                        selected: true
+                        selected: isSemver
                     };
                     discoveredFiles.push(descriptor);
                     logger.debug('version-manager - discoverVersionFiles', 'Found version file', {
@@ -285,19 +286,19 @@ export function discoverVersionFiles(options = {}) {
         return a.relativePath.localeCompare(b.relativePath);
     });
 
-    // Determine resolved version (prefer root-level file, then first found)
+    // Determine resolved version from semver files only (prefer root-level, then first found)
     let resolvedVersion = null;
-    const rootFile = discoveredFiles.find((f) => !f.relativePath.includes(path.sep));
+    const semverFiles = discoveredFiles.filter((f) => f.selected);
+    const rootFile = semverFiles.find((f) => !f.relativePath.includes(path.sep));
     if (rootFile && rootFile.version) {
         resolvedVersion = rootFile.version;
-    } else if (discoveredFiles.length > 0) {
-        // Use first file's version as fallback
-        const firstWithVersion = discoveredFiles.find((f) => f.version !== null);
+    } else if (semverFiles.length > 0) {
+        const firstWithVersion = semverFiles.find((f) => f.version !== null);
         resolvedVersion = firstWithVersion ? firstWithVersion.version : null;
     }
 
-    // Check for version mismatch
-    const versions = discoveredFiles.filter((f) => f.version !== null).map((f) => f.version);
+    // Check for version mismatch (only among semver files)
+    const versions = semverFiles.filter((f) => f.version !== null).map((f) => f.version);
     const uniqueVersions = [...new Set(versions)];
     const mismatch = uniqueVersions.length > 1;
 
@@ -1149,24 +1150,36 @@ export function compareVersions(version1, version2) {
  *
  * @returns {Promise<Object>} Validation result with alignment status and issues
  */
-export async function validateVersionAlignment() {
-    logger.debug('version-manager - validateVersionAlignment', 'Validating version alignment');
+export async function validateVersionAlignment(baseBranch = null) {
+    logger.debug('version-manager - validateVersionAlignment', 'Validating version alignment', {
+        baseBranch
+    });
 
     try {
         // Discover all version files
         const discovery = discoverVersionFiles();
 
-        // Get git tag version (parseTagVersion returns null for non-semver tags)
-        const { getLatestLocalTag, parseTagVersion } = await import('./git-tag-manager.js');
-        const latestTag = getLatestLocalTag();
+        // Get git tag version scoped to HEAD when baseBranch is provided
+        const {
+            getLatestLocalTag, getLatestLocalTagOnBranch,
+            parseTagVersion,
+            getLatestRemoteTag, getLatestRemoteTagOnBranch
+        } = await import('./git-tag-manager.js');
+        const latestTag = baseBranch ? getLatestLocalTagOnBranch(baseBranch) : getLatestLocalTag();
         const tagVersion = latestTag ? parseTagVersion(latestTag) : null;
 
         // Get CHANGELOG version
         const changelogVersion = readChangelogVersion();
-
-        // Get remote tag version (parseTagVersion returns null for non-semver tags)
-        const { getLatestRemoteTag } = await import('./git-tag-manager.js');
-        const latestRemoteTag = await getLatestRemoteTag();
+        let latestRemoteTag;
+        if (baseBranch) {
+            latestRemoteTag = getLatestRemoteTagOnBranch(baseBranch);
+            // Fall back to global if branch-scoped lookup returns nothing
+            if (!latestRemoteTag) {
+                latestRemoteTag = await getLatestRemoteTag();
+            }
+        } else {
+            latestRemoteTag = await getLatestRemoteTag();
+        }
         const remoteVersion = latestRemoteTag ? parseTagVersion(latestRemoteTag) : null;
 
         // Collect all local versions

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.61.2",
+    "version": "2.66.1",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {
@@ -16,6 +16,8 @@
         "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
         "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
         "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+        "test:e2e": "bash test/manual/sdlc-stability-check.sh",
+        "test:full": "npm run test:all && npm run test:e2e",
         "lint": "eslint lib/ bin/claude-hooks .library/librarian/",
         "lint:fix": "eslint lib/ bin/claude-hooks .library/librarian/ --fix",
         "format": "prettier --write \"lib/**/*.js\" \"bin/**\" \"test/**/*.js\"",