claude-git-hooks 2.66.1 → 2.68.0

package/CHANGELOG.md

@@ -5,21 +5,112 @@ 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.68.0] - 2026-06-12
+
+### ✨ Added
+- Silent, throttled pre-command auto-update guard that checks for newer versions before running commands and self-updates automatically (#196)
+- New `autoUpdate` configuration section with `enabled` (default: true) and `intervalHours` (default: 24) settings to control automatic update behavior
+- Centralized `lib/utils/auto-update.js` module providing shared update logic (`getUpdateStatus`, `performUpdate`, `shouldAutoCheck`, `maybeAutoUpdate`) for all update paths
+
+### 🔧 Changed
+- Refactored `update` command into a thin wrapper over the shared auto-update module, eliminating duplicated version-check and npm-install logic
+- Refactored install-time update prompt to use shared `getUpdateStatus()` and `performUpdate()` instead of inline implementation
+- Auto-update is fully fail-open and skipped in `--headless` mode — never blocks the real command on failure
+- Excluded fast/offline commands (`update`, `install`, `uninstall`, `help`, `version`, `migrate-config`) from the pre-command auto-update check to avoid recursion and unnecessary latency
+
+### 🐛 Fixed
+- Fixed install-time update prompt incorrectly offering to "update" dev builds that are ahead of the latest published npm version
+
+### 🗑️ Removed
+- Removed `check-version.sh` template installation from the install command (replaced by the integrated auto-update guard)
+- Removed inline `npm install -g` and `runInstall(['--force'])` calls from `update.js` and `install.js` in favor of centralized `performUpdate()`
+
+
+## [2.67.3] - 2026-06-12
+
+### ✨ Added
+- Upfront CLI availability probe in gotcha solicitation — checks once per run instead of discovering failures per-book (#195)
+- New `llm.js` shared CLI wrapper for the librarian pipeline, using the developer's `claude` login session
+
+### 🔧 Changed
+- Replaced Anthropic SDK (`@anthropic-ai/sdk`) with CLI wrapper (`llm.js`) in the librarian's candidate-text-generator (#195)
+- Default model identifier simplified from `claude-sonnet-4-6` to `sonnet` shorthand
+- Gotcha solicitation skips per-book candidate generation entirely when CLI is unavailable, showing a single message instead of one warning per book
+- Tests updated to mock the CLI wrapper instead of the Anthropic SDK
+
+### 🐛 Fixed
+- Resolved library pipeline resolver issues when Anthropic API key is unavailable — librarian now works with just a `claude` CLI login (#195)
+
+### 🗑️ Removed
+- Removed `_classifyError()` helper and all SDK-specific error classification logic from candidate-text-generator
+- Removed direct dependency on `@anthropic-ai/sdk` in the librarian pipeline
+
+
+## [2.67.2] - 2026-06-11
+
+### 🔧 Changed
+- Centralized `.library/` resolution into a dedicated `library-resolver.js` module — all commands now resolve Library paths from the repo root via `libraryModuleUrl()` instead of fragile relative imports
+- Library pipeline steps (staleness checks, verification gates, co-change pipeline) now gracefully skip with a debug log when the working repo has no `.library/` directory
+
+### 🐛 Fixed
+- Commands no longer produce misleading warnings or errors when the tool is installed as a dependency in repos that have no `.library/` (#194)
+- Sanitized version output at source (#194)
+
+
+## [2.67.1] - 2026-06-11
+
+### 🐛 Fixed
+- Sanitized non-semver versions at discovery source in version-manager, preventing invalid version strings from propagating through the bump-version pipeline
+
+### 🗑️ Removed
+- Removed unused `test:full` npm script from package.json
+
+
+## [2.67.0] - 2026-06-10
+
+### ✨ Added
+
+- Integrated the `@mscope/automation-skills` rule registry into the pre-commit hook: deterministic JBE/UIK rule checks run against staged files and surface findings alongside lint + AI output, with optional severity gating via `skillRegistry.blockOn` (Options A + G)
+- Injected the mscope rule catalogue into the Claude analysis prompt; findings Claude cannot classify against the catalogue are appended as `[skill-gap]` candidates to the skill repo's `skill-feedback.md`, fingerprint-deduplicated and reviewed via `automation-skills retro` — never auto-merged (Option E2)
+- Lessons-learned capture on `create-pr`: a new knowledge-capture step hands control to `automation-skills resume` before tags are pushed, recording branch lessons to the skill repo's `implementation-history.md` (supersedes the draft `finish-branch` command; gated by `skillRegistry.resumeOnCreatePr`, skipped in headless mode)
+- `skillRegistry` configuration section (`enabled`, `blockOn`, `resumeOnCreatePr`) registered in package defaults, overridable remotely and per-repo, documented in `config.advanced.example.json`
+- Unit tests for the skill-registry: parser, runner, catalogue, feedback-writer, facade, and resume modules
+
+### 🔧 Changed
+
+- Skill-registry consumption is decoupled behind a facade (`runSkillChecks`, `getCatalogueSection`, `recordSkillGaps`) with a memoized registry load; the catalogue reaches the analysis prompt as a plain parameter threaded through `analysis-engine` → `prompt-builder`, which have no skill-registry knowledge
+- `analyze` command injects the same rule catalogue into its analysis prompt for parity with pre-commit
+- `CLAUDE_ANALYSIS_PROMPT.md` now instructs Claude to classify each finding against the injected catalogue via `details[].rule`
+- Library extractor cross-references now resolve through books' frontmatter `source_files` instead of source-file basenames, so books not named after their source (e.g. `skill-registry-parser.md`) survive regeneration with correct references
+
+### 🐛 Fixed
+
+- Resolved the `automation-skills` sibling skill repo relative to the working repo (env vars → sibling-of-working-repo) instead of guessing under the user's home directory, making registry loading reliable across machines
+- Fixed catalogue injection never activating in the canonical sibling layout — the registry was loaded without the working repo root, so resolution silently failed unless an env var was set
+- Repaired skill-registry text injections that were being corrupted by suggestion-click commits
+- Skill-gap writer failures during pre-commit are now logged as warnings instead of silently discarded (the commit is never blocked either way)
+
+### 🗑️ Removed
+
+- Removed the legacy `mscope-automation--claude-skills` sibling skill-repo name from registry resolution, leaving only the current `automation-skills` name
+
 ## [2.66.1] - 2026-06-10
 
 ### 🐛 Fixed
-- Normalized path separators to forward slashes in staleness checker for cross-platform compatibility
 
+- 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
@@ -27,6 +118,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
@@ -35,12 +127,13 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - Fixed stale git worktree leftovers causing integration test failures
 
 ### 🗑️ Removed
-- Removed per-file custom version entry option (`promptEditField`) from `bump-version` interactive selection
 
+- 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)
@@ -48,6 +141,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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
@@ -56,6 +150,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
@@ -63,13 +158,14 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
@@ -77,6 +173,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
@@ -84,18 +181,20 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
 
+- 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
@@ -103,6 +202,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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
@@ -110,19 +210,21 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
@@ -131,6 +233,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
@@ -138,42 +241,47 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
 
+- 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)
@@ -181,15 +289,16 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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

package/README.md

@@ -308,6 +308,39 @@ claude-hooks batch-info
 # Shows: per-model average analysis time and orchestration overhead (from telemetry)
 ```
 
+### mscope Skill-Registry Integration (automation-skills)
+
+Connects the hooks to the `@mscope/automation-skills` rule registry. No new commands — the integration runs inside `pre-commit` and `create-pr`.
+
+```bash
+# Setup (one of):
+git clone https://github.com/mscope-S-L/automation-skills ../automation-skills   # sibling of your repo
+export CLAUDE_HOOKS_SKILL_REPO=/path/to/automation-skills                        # or explicit path
+
+# Optional — enables freshness checks and lessons-learned capture:
+npm install -g github:mscope-S-L/automation-skills
+```
+
+**What it does on every commit:**
+
+- Runs the registry's deterministic JBE/UIK rule checks against staged files and shows findings alongside lint + AI output (warn-only by default)
+- Injects the rule catalogue into the Claude analysis prompt so AI findings are classified against rule IDs
+- Findings the AI cannot classify are appended as `[skill-gap]` candidates to the **sibling skill repo's** `skill-feedback.md` (a cross-repo write — uncommitted, fingerprint-deduplicated, reviewed later via `automation-skills retro`, never auto-merged into the registry)
+
+**What it does on `create-pr`:**
+
+- Hands control to `automation-skills resume` (interactive) to record the branch's lessons-learned before tags are pushed. Skipped in headless mode or when the CLI is not installed.
+
+**Configuration** (`.claude/config.json` overrides):
+
+| Key | Default | Effect |
+| --- | --- | --- |
+| `skillRegistry.enabled` | `true` | Master switch for the whole integration |
+| `skillRegistry.blockOn` | `"never"` | Block commits at/above a severity: `critical`, `high`, `medium`, `low` |
+| `skillRegistry.resumeOnCreatePr` | `true` | Lessons-learned capture during `create-pr` |
+
+**Use case:** team-wide antipattern enforcement with a feedback loop — the registry teaches the hooks, and unrecognized findings feed back into the registry. Everything silently no-ops when the skill repo isn't found; the integration is value-add, never a hard dependency.
+
 ### Other Commands
 
 ```bash
@@ -574,6 +607,7 @@ claude-hooks batch-info   # Shows config + per-model avg speed from telemetry
 - Max files per commit: 30
 - Orchestrator threshold: 3 files
 - Orchestrator model: opus (internal, not configurable)
+- Skill registry: enabled, `blockOn: never` (warn-only), `resumeOnCreatePr: true` — silently inactive when the automation-skills repo isn't found
 
 ---
 

package/bin/claude-hooks

@@ -131,6 +131,25 @@ async function main() {
         logger.debug('bin - main', 'Authorization guard bypassed (--headless)', { command: entry.name });
     }
 
+    // --- Pre-command auto-update guard (silent, throttled) ---
+    // Single choke-point: every command flows through here, so auto-update is added
+    // once instead of in each command file. Mirrors the authorization guard above.
+    // Fully fail-open — never blocks the real command.
+    if (!isHeadless) {
+        try {
+            const { maybeAutoUpdate } = await import('../lib/utils/auto-update.js');
+            const updated = await maybeAutoUpdate(entry.name);
+            if (updated) {
+                // The running binary was just replaced; user must re-run their command.
+                process.exit(0);
+            }
+        } catch (err) {
+            logger.debug('bin - main', 'Pre-command auto-update skipped (non-fatal)', {
+                error: err.message
+            });
+        }
+    }
+
     // --- Commands with special argument handling ---
 
     // analyze: translate flags to options object

package/lib/commands/analyze-diff.js

@@ -7,6 +7,7 @@ import fs from 'fs';
 import { analyzeBranchForPR } from '../utils/pr-metadata-engine.js';
 import { getConfig } from '../config.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { colors, error, info, checkGitRepo } from './helpers.js';
 
 /**
@@ -93,31 +94,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}`);
+        // Library staleness section (only when the working repo has its own .library/)
+        if (hasLibrary()) {
+            try {
+                const { runAll } = await import(libraryModuleUrl('tools/staleness.js'));
+                const { getSourceDir, getBooksDir } = await import(libraryModuleUrl('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');
                 }
-                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');
             }
-        } catch {
-            logger.warning('📚 Library staleness check unavailable — .library/ tools not found');
         }
 
         // Save the results in a file with context

package/lib/commands/analyze.js

@@ -43,6 +43,7 @@ import { generateResolutionPrompt } from '../utils/resolution-prompt.js';
 import { getConfig } from '../config.js';
 import { loadPreset } from '../utils/preset-loader.js';
 import { CostTracker } from '../utils/cost-tracker.js';
+import { getCatalogueSection } from '../utils/skill-registry/index.js';
 import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
 import { error, success, info } from './helpers.js';
@@ -219,7 +220,8 @@ export const runAnalyze = async (options = {}) => {
         const result = await runAnalysis(filesData, config, {
             hook: 'analyze',
             headless,
-            costTracker
+            costTracker,
+            catalogueSection: getCatalogueSection({ repoRoot: getRepoRoot() })
         });
 
         // Write hooks-verified marker when analysis completes without critical/blocker issues.

package/lib/commands/back-merge.js

@@ -58,6 +58,7 @@ import {
     promptConfirmation
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { colors, error, checkGitRepo } from './helpers.js';
 
 /** Default source branch for back-merge */
@@ -652,50 +653,55 @@ export async function runBackMerge(args) {
     console.log('');
 
     // 14b. Co-change correlation pipeline (AUT-3777)
+    // Only runs when the working repo has its own .library/ (the tool ships without one).
     let coChangeReport = null;
-    try {
-        const { coChangePipeline } = await import('../../.library/librarian/index.js');
+    if (!hasLibrary()) {
+        logger.debug('back-merge', 'No .library/ in current repo — skipping co-change pipeline');
+    } else {
+        try {
+            const { coChangePipeline } = await import(libraryModuleUrl('librarian/index.js'));
 
-        showInfo('Running co-change correlation pipeline...');
-        const summary = coChangePipeline({ repoCtx: {} });
-        const { modifiedFiles, perStep, report, warnings, mode } = summary;
+            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);
-        }
+            // 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;
+            // 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}`);
+            if (modifiedFiles.length === 0) {
+                showInfo('Co-change pipeline produced no Library changes');
             } else {
-                const windowDesc = tagName ? `${tagName}..HEAD` : 'full history';
-                const libCommitMsg = `chore(library): co-change correlations for ${windowDesc}`;
-                const libCommit = createCommit(libCommitMsg);
+                const root = getRepoRoot();
+                const absFiles = modifiedFiles.map(f => path.isAbsolute(f) ? f : path.join(root, f));
+                const stageResult = stageFiles(absFiles);
 
-                if (!libCommit.success) {
-                    showWarning(`Failed to commit co-change files: ${libCommit.error}`);
+                if (!stageResult.success) {
+                    showWarning(`Failed to stage co-change files: ${stageResult.error}`);
                 } else {
-                    showSuccess(`Co-change committed: ${libCommitMsg} (${modifiedFiles.length} file(s))`);
+                    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 });
         }
-    } catch (err) {
-        logger.warning(`co-change pipeline skipped: ${err.message}`);
-        logger.debug('back-merge', 'Co-change pipeline skipped', { error: err.message });
     }
 
     // 15. Verify sync

package/lib/commands/bump-version.js

@@ -24,8 +24,7 @@ import {
     discoverVersionFiles,
     incrementVersion,
     modifySuffix,
-    updateVersionFiles,
-    validateVersionFormat
+    updateVersionFiles
 } from '../utils/version-manager.js';
 import { createTag, pushTags, tagExists, formatTagName } from '../utils/git-tag-manager.js';
 import {
@@ -51,6 +50,7 @@ import {
     promptToggleList
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
+import { libraryModuleUrl, hasLibrary } from '../utils/library-resolver.js';
 import { colors, error, checkGitRepo } from './helpers.js';
 import {
     CONSOLE_WARNING_TEMPLATE,
@@ -414,20 +414,25 @@ 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();
+    // Library verification gate — silent on clean, loud-warn on stale, never-hard-fail.
+    // Only runs when the working repo has its own .library/ (the tool ships without one).
+    if (!hasLibrary()) {
+        logger.debug('bump-version', 'No .library/ in current repo — skipping Library verification gate');
+    } else {
+        logger.debug('bump-version', 'Running Library verification gate');
+        try {
+            const { verify } = await import(libraryModuleUrl('librarian/index.js'));
+            const verifyResult = await verify();
 
-        if (verifyResult.clean) {
-            logger.debug('bump-version', 'Library is clean — no warning needed');
-        } else {
-            _emitLibraryWarning(verifyResult);
+            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);
         }
-    } 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
@@ -478,7 +483,7 @@ export async function runBumpVersion(args) {
         ? uniqueSelected[0]
         : discovery.resolvedVersion;
 
-    if (!currentVersion || !validateVersionFormat(currentVersion)) {
+    if (!currentVersion) {
         showError('Could not determine a valid semver version from selected files');
         process.exit(1);
     }