claude-git-hooks 2.44.0 → 2.51.2

package/CHANGELOG.md

@@ -5,6 +5,153 @@ 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.51.2] - 2026-05-26
+
+### 🔧 Changed
+- Made library integration visible in CLI (#164)
+
+### 🐛 Fixed
+- Fixed partial file selection during version bump — `updateVersionFiles` no longer silently skips unselected files; callers now filter before calling, ensuring only user-selected files are bumped (AUT-3733)
+
+
+## [2.51.1] - 2026-05-25
+
+### ✨ Added
+- Specification guide (SPEC_GUIDE.md) — a practitioner's guide to building a Code Knowledge Library, covering setup, schema, taxonomy, maintenance, and worked examples (AUT-3722)
+- Overlap-check tool for detecting book content overlap, closing Library milestone M4 (AUT-3722, #162)
+- Maps/ artifacts (dependency graph, co-change seeds) surfaced via librarian module for programmatic access (AUT-3722)
+
+### 🔧 Changed
+- Rewrote Library README as a specification-oriented guide with clearer structure, worked examples, milestone status tracking, and getting-started table (AUT-3722)
+- Rewrote CLAUDE.md Library section to align with specification guide format and reference SPEC_GUIDE.md (AUT-3722)
+- Made Library integration visible in CLI output so users can discover library-powered features (#163)
+
+
+## [2.51.0] - 2026-05-25
+
+### ✨ Added
+- Added unified Library CLI at `.library/bin/library` with commands: check, regenerate, extract, tokens, graph, inject, validate, report (AUT-3272)
+- Added centralized path resolution module (`.library/paths.js`) with resolver.yaml parser for repository-agnostic Library adoption
+- Added Library CLI command registry (`.library/cli.js`) following the same pattern as `lib/cli-metadata.js`
+- Added Library staleness checks to workflow commands: non-blocking warnings in `pre-commit`, `analyze-diff`, and `create-pr`; blocking gates in `create-release` and `close-release` (AUT-3272)
+- Added co-change reference injection to `back-merge` command — automatically refreshes Library references after post-deploy merge (AUT-3272)
+- Added `source:` field to `resolver.yaml` for configurable source directory resolution
+- Added M5 validation results to Library README — hypothesis validated with modest effect size (0.7% mean token reduction, 8/8 accuracy parity)
+- Added npm scripts for all Library CLI commands: `library:check`, `library:regenerate`, `library:extract`, `library:validate`, `library:report`
+- Added N-gram overlap-check tool that compares CLAUDE.md against Library files, audits pointers, and categorises retained sections (AUT-3722)
+- Added Specification Guide (SPEC_GUIDE.md) — a self-contained practitioner's guide for building a Code Knowledge Library in any repository (AUT-3722)
+- Added maps/ artifact resolution to librarian — direct access via @maps/ paths and heuristic routing for co-change, dependency graph, and methodology queries (AUT-3722)
+- Added co-change references to books via PR #161 (AUT-3315)
+
+### 🔧 Changed
+- Refactored all Library tools (`staleness.js`, `generate-graph.js`, `inject-co-change.js`, `measure-tokens.js`, `extract.js`, `librarian/index.js`) to use centralized `paths.js` instead of per-tool `__dirname` arithmetic (AUT-3272)
+- Rewrote `.library/README.md` with adoption guide, command reference, book schema documentation, and automated maintenance via git hooks section
+- Replaced legacy npm scripts (`library:tokens`, `library:graph`, `library:extract-poc`, `library:inject-co-change`) with unified CLI-routed equivalents
+- Updated `jest.config.js` to ignore tests inside `.claude/worktrees/` directories
+- Bumped `last_verified` dates to 2026-05-22 across all 70 Library books
+- Rewrote Library README as a specification-oriented guide — restructured around how the Library works (books, indexes, resolver, librarian, auto-generation) rather than operational steps (AUT-3722)
+- Rewrote CLAUDE.md Library section to reference the Specification Guide instead of duplicating Library documentation (AUT-3722)
+- Closed M4 milestone — resolved OPEN items 1–5 in SPEC_GUIDE § 13 with evidence and deferral justifications (AUT-3722)
+
+
+## [2.50.0] - 2026-05-20
+
+### ✨ Added
+- Added co-change reference tracking to library books — frontmatter now includes `co_change_references` with commit counts, confidence scores, and trigger descriptions for files that historically change together (AUT-3315)
+- Added `CO_CHANGE_SEEDS.md` co-change seed patterns document with 4 architectural coupling patterns mined from 6 months of git history (AUT-3315)
+- Added `inject-co-change.js` CLI tool to inject co-change references from seed patterns into book frontmatter, with `--dry-run`, `--json`, and `--seeds` options (AUT-3315)
+- Added librarian module for automated library maintenance pipeline (#160)
+
+### 🔧 Changed
+- Moved staleness detection scripts from `.library/maintenance/` to `.library/tools/` directory (AUT-3315)
+- Updated `.library/maps/` directory scope to include co-change seeds and token reports (AUT-3315)
+- Updated `.library/tools/` directory scope to cover all standalone CLI utilities — staleness, graph, tokens, and co-change injection (AUT-3315)
+
+
+## [2.49.0] - 2026-05-19
+
+### ✨ Added
+- Librarian module for Library maintenance pipeline with five core functions: fetch, regenerate, checkOverflow, solicitGotchas, and buildReport (AUT-3309)
+- Execution prompt for running full regeneration cycles via Sonnet sessions (AUT-3309)
+- Report template for structured maintenance cycle output (AUT-3309)
+- Staleness detector for tracking book drift via AST hash comparison (#159, AUT-3307)
+
+### 🔧 Changed
+- Renamed librarian `fetch` export to `fetchLibraryContent` for clarity (AUT-3309)
+- Updated Library README with comprehensive documentation covering auto-generation, staleness detection, librarian module, and maintenance workflow
+- Book schema `generated_from` field now supports AST hash format (`ast:sha256:<hex>`) for staleness tracking
+- Library book count updated from 26 to 70 reflecting auto-generated coverage
+
+
+## [2.48.0] - 2026-05-19
+
+### ✨ Added
+- Added staleness detector for library books to identify outdated documentation (AUT-3307)
+
+### 🗑️ Removed
+- Removed extractor evaluation artifacts (PARSER_DECISION.md, QUALITY_GAP.md) after library auto-update evaluation completed (#158, AUT-3305)
+
+
+## [2.47.1] - 2026-05-19
+
+### 🐛 Fixed
+- Fixed path normalization in AST extractor for Windows compatibility by using `fileURLToPath()` instead of raw URL pathname and normalizing backslashes in relative paths (AUT-3305)
+- Fixed cross-platform book file detection in help catalog by using regex path separator matching instead of literal forward slash
+
+
+## [2.47.0] - 2026-05-19
+
+### ✨ Added
+- Quality gap report and batch runner for the AST documentation extractor (AUT-3305)
+- "preserve-if-filled" strategy for the AST extractor to retain manually-written book sections during regeneration (AUT-3305)
+
+### 🔧 Changed
+- Regenerated all library book documentation from AST extractor output, replacing manually-maintained books with accurate cross-references and call signatures (AUT-3305, PR #157)
+
+
+## [2.46.0] - 2026-05-18
+
+### ✨ Added
+- Added AST extractor POC with JavaScript and Python language adapters (AUT-3273)
+- Added source-to-book auto-section generator for automated library documentation (AUT-3273)
+- Generated book stubs for 40 source modules in `.library/books/` (AUT-3273)
+- Added centralized configuration registry (`config-registry.js` + `defaults.json`) with remote override support (#156, ISSUE-138)
+
+### 🔧 Changed
+- Configuration merge priority expanded from 4 to 5 layers, adding remote `settings.json` team-policy overrides (#156)
+- Orchestrator model, threshold, and timeout are now configurable via remote `settings.json` instead of hardcoded values (#156)
+- Judge timeout now configurable via remote `settings.json` (#156)
+- Updated library README and shelf indexes to reflect new book count (AUT-3273)
+- ESLint config updated to include `.library/extractor/` files (AUT-3273)
+
+
+## [2.45.0] - 2026-05-13
+
+### ✨ Added
+- Added centralized config-registry module with local defaults and remote override support (SUE-138)
+- Added lib/defaults.json as the single source of truth for all package default values (SUE-138)
+
+### 🔧 Changed
+- Replaced inline hardcoded constants across modules with config-registry lookups — judge, orchestrator, Linear connector, model aliases, linter tools, and PR analysis categories now read from defaults.json with remote override capability (SUE-138)
+- Updated config merge priority to HARDCODED < remote settings.json < defaults < preset < user overrides (SUE-138)
+- Added config-registry mocks to unit tests for modules consuming centralized defaults (SUE-138)
+
+### 🐛 Fixed
+- Fixed Linear ticket fetch issue (#155)
+
+
+## [2.44.1] - 2026-05-13
+
+### ✨ Added
+- Added unit tests for linear-connector module covering ticket extraction, parsing, token loading, connection testing, and ticket fetching (SUE-154)
+
+### 🐛 Fixed
+- Fixed help command to cap book reads at 5 in Pass 2, preventing oversized prompts when the LLM requests too many library books (SUE-154)
+
+### 🗑️ Removed
+- Removed CLAUDE-MIGRATION.md — migration map no longer needed after library stabilization
+
+
 ## [2.44.0] - 2026-05-04
 
 ### ✨ Added

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/analyze-pr.js

@@ -33,6 +33,7 @@ import { promptConfirmation, promptMenu } from '../utils/interactive-ui.js';
 import { CostTracker } from '../utils/cost-tracker.js';
 import { colors, error, fatal, info, warning, checkGitRepo } from './helpers.js';
 import logger from '../utils/logger.js';
+import { resolveSection } from '../utils/config-registry.js';
 import path from 'path';
 
 // ─── JSON Error Helper ────────────────────────────────────────────────────
@@ -380,23 +381,14 @@ export async function runAnalyzePr(args) {
             warning(`Could not load preset "${presetName}" guidelines, using defaults`);
         }
 
-        // Step 7: Build category strings from config
-        const inlineCategories = config.prAnalysis?.inlineCategories || [
-            'bug',
-            'security',
-            'performance',
-            'hotspot'
-        ];
-        const generalCategories = config.prAnalysis?.generalCategories || [
-            'ticket-alignment',
-            'scope',
-            'style',
-            'good-practice',
-            'extensibility',
-            'observability',
-            'documentation',
-            'testing'
-        ];
+        // Step 7: Build category strings from config (remote categories.json > local defaults)
+        // Categories are guaranteed by defaults.json loaded at import time via config-registry.
+        // The || [] fallback guards against unexpected config corruption or a missing section.
+        const resolvedPrAnalysis = await resolveSection('prAnalysis');
+        const inlineCategories = resolvedPrAnalysis?.inlineCategories ||
+            config.prAnalysis?.inlineCategories || [];
+        const generalCategories = resolvedPrAnalysis?.generalCategories ||
+            config.prAnalysis?.generalCategories || [];
         const allCategories = [...inlineCategories, ...generalCategories];
 
         const inlineCategoriesStr = inlineCategories.map((c) => `- \`${c}\``).join('\n');

package/lib/commands/back-merge.js

@@ -719,6 +719,20 @@ export async function runBackMerge(args) {
         await _revertFollowup(rcBranchForLog, repoRoot);
     }
 
+    // 18b. Co-change injection — refresh library references with newly merged history
+    if (pushStatus === 'pushed') {
+        try {
+            const { main: injectCoChange } = await import('../../.library/tools/inject-co-change.js');
+            showInfo('📚 Refreshing library co-change references...');
+            await injectCoChange(['node', 'inject-co-change.js']);
+            showSuccess('✓ Co-change references updated');
+        } catch (err) {
+            showWarning('📚 Co-change injection unavailable — .library/ tools not found');
+            logger.debug('back-merge', 'Co-change injection skipped', { error: err.message });
+        }
+        console.log('');
+    }
+
     // 19. Summary
     console.log('');
     console.log(`${colors.green}═════════════════════════════════════════════════${colors.reset}`);

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

@@ -765,6 +765,38 @@ export async function runCreatePr(args) {
             finalBody = `> ⚠️ This PR must be merged with **merge commit** (not squash)\n\n${prBody}`;
         }
 
+        // Library staleness section — informational, non-blocking
+        try {
+            showInfo('📚 Checking library staleness...');
+            const { checkBook } = await import('../../.library/tools/staleness.js');
+            const { getBooksDir } = await import('../../.library/paths.js');
+            const { getRepoRoot } = await import('../utils/git-operations.js');
+            const booksDir = getBooksDir();
+            const root = getRepoRoot();
+            const changedSourceFiles = (filesArray || [])
+                .map(f => f.path || f)
+                .filter(p => p.startsWith('lib/') && p.endsWith('.js'));
+            const staleBooks = [];
+            for (const srcPath of changedSourceFiles) {
+                const bookName = `${srcPath.replace(/^lib\/.*\//, '').replace(/\.js$/, '')}.md`;
+                try {
+                    const result = await checkBook(path.join(booksDir, bookName), root);
+                    if (result.status === 'stale') staleBooks.push(bookName);
+                } catch {
+                    // skip
+                }
+            }
+            if (staleBooks.length > 0) {
+                const bookList = staleBooks.map(b => `- \`${b}\``).join('\n');
+                finalBody += `\n\n---\n\n### 📚 Library Staleness\n\nThe following library books may need regeneration:\n\n${bookList}\n\nRun: \`npm run library:regenerate\``;
+                showWarning(`📚 ${staleBooks.length} stale book(s) — section added to PR body`);
+            } else if (changedSourceFiles.length > 0) {
+                showSuccess('📚 Library books are current');
+            }
+        } catch {
+            showWarning('📚 Library staleness check unavailable — .library/ tools not found');
+        }
+
         // Step 10: Get reviewers from team + config fallback
         logger.debug('create-pr', 'Step 10: Selecting reviewers via team resolution');
         const reviewers = await selectReviewers({

package/lib/commands/create-release.js

@@ -388,6 +388,28 @@ export async function runCreateRelease(args) {
         const config = await getConfig();
         const selectedFiles = discovery.files.filter((f) => f.selected);
 
+        // Library staleness gate — block release 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) {
+                showError('📚 Library staleness detected — cannot create release with stale books');
+                process.stdout.write(formatHuman(stalenessResult));
+                showError('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('create-release', 'Library staleness check skipped', { error: err.message });
+        }
+
         // Step 6: Create RC branch from develop
         logger.debug('create-release', 'Step 6: Creating RC branch', { rcBranch });
         showInfo(`Creating branch ${rcBranch} from ${SOURCE_BRANCH}...`);

package/lib/commands/help.js

@@ -18,6 +18,7 @@ import { fetchFileContent, fetchDirectoryListing, createIssue } from '../utils/g
 import { promptMenu, promptEditField, promptConfirmation } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
 import { commands } from '../cli-metadata.js';
+import { fetchLibraryContent as librarianFetch } from '../../.library/librarian/index.js';
 
 /**
  * Get claude-hooks source repo coordinates from package.json
@@ -164,11 +165,13 @@ function printAiResponse(response, source) {
 const _packageRoot = path.join(__dirname, '..', '..');
 
 /**
- * Catalog directories within .library/ to auto-discover
- * Why: These contain index and shelf files that form the navigational catalog.
- * books/ is excluded — those are fetched on-demand in Pass 2.
+ * Maximum number of books to read in Pass 2.
+ * Why: Matches the "do not request more than 5" instruction in HELP_NAVIGATE.md.
+ * Caps LLM-sourced lists to prevent oversized prompts that would fail the second call.
  */
-const _CATALOG_DIRS = ['by-code', 'by-domain', 'by-task-type'];
+const MAX_BOOKS = 5;
+
+// Catalog routing delegated to the librarian module; see .library/librarian/
 
 /**
  * Read a single file from package root, returning null on failure
@@ -187,67 +190,27 @@ const _readPackageFile = async (relativePath) => {
 /**
  * Read the project catalog from .library/ and CLAUDE.md
  * Why: The catalog provides navigational context for the AI librarian (Pass 1).
- * Auto-discovers index/shelf files so the catalog stays current as .library/ grows.
- *
- * Reads:
- * - CLAUDE.md (global rules)
- * - .library/index.md (repo identity, capabilities)
- * - .library/conventions.md (coding standards)
- * - .library/by-code/*.md (source-path shelves)
- * - .library/by-domain/*.md (workflow reading lists)
- * - .library/by-task-type/*.md (task guidance)
+ * Delegates to the librarian module for directory discovery and routing.
  *
  * @returns {Promise<string|null>} Concatenated catalog or null if nothing could be read
  */
 const readLibraryCatalog = async () => {
-    const sections = [];
-
-    // Fixed files: CLAUDE.md + core library files
-    const fixedFiles = [
-        { label: 'CLAUDE.md', path: 'CLAUDE.md' },
-        { label: '.library/index.md', path: '.library/index.md' },
-        { label: '.library/conventions.md', path: '.library/conventions.md' }
-    ];
-
-    for (const file of fixedFiles) {
-        const content = await _readPackageFile(file.path);
-        if (content) {
-            sections.push(`--- ${file.label} ---\n${content}`);
-        }
-    }
-
-    // Auto-discover .md files in each catalog directory
-    for (const dir of _CATALOG_DIRS) {
-        const dirPath = path.join(_packageRoot, '.library', dir);
-        let entries;
-        try {
-            entries = await fs.readdir(dirPath);
-        } catch {
-            logger.debug('help - readLibraryCatalog', `Could not read .library/${dir}/`);
-            continue;
-        }
-
-        const mdFiles = entries.filter((f) => f.endsWith('.md')).sort();
-        for (const file of mdFiles) {
-            const relativePath = `.library/${dir}/${file}`;
-            const content = await _readPackageFile(relativePath);
-            if (content) {
-                sections.push(`--- ${relativePath} ---\n${content}`);
-            }
+    // Fetching delegated to the librarian module; see .library/librarian/
+    try {
+        const result = await librarianFetch(null, { repoRoot: _packageRoot, full: true });
+        if (result.catalog) {
+            logger.debug('help - readLibraryCatalog', 'Catalog loaded via librarian', {
+                files: result.readingList.length,
+                length: result.catalog.length
+            });
         }
-    }
-
-    if (sections.length === 0) {
-        logger.debug('help - readLibraryCatalog', 'No catalog files found');
+        return result.catalog;
+    } catch (err) {
+        logger.debug('help - readLibraryCatalog', 'Librarian fetch failed', {
+            error: err.message
+        });
         return null;
     }
-
-    const catalog = sections.join('\n\n');
-    logger.debug('help - readLibraryCatalog', 'Catalog loaded', {
-        sections: sections.length,
-        length: catalog.length
-    });
-    return catalog;
 };
 
 /**
@@ -346,6 +309,14 @@ async function readAndAnswerWithBooks(booksLine, question, catalog) {
             return null;
         }
 
+        if (bookPaths.length > MAX_BOOKS) {
+            logger.debug('help - readAndAnswerWithBooks', 'Capping book list', {
+                requested: bookPaths.length,
+                max: MAX_BOOKS
+            });
+            bookPaths.length = MAX_BOOKS;
+        }
+
         logger.debug('help - readAndAnswerWithBooks', 'Reading books from disk', { bookPaths });
 
         // Read books from local filesystem in parallel