claude-git-hooks 2.43.0 → 2.44.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.44.0] - 2026-05-04
+
+### ✨ Added
+- New `HELP_NAVIGATE.md` prompt template for the first-pass catalog navigation (SUE-152)
+- Auto-discovery of `.library/` catalog files (by-code, by-domain, by-task-type shelves) for AI help context
+
+### 🔧 Changed
+- Rewrote AI help command to use a two-pass librarian approach navigating local `.library/` instead of single-pass CLAUDE.md lookup (SUE-152)
+- Pass 1 sends project catalog to Claude; if deeper detail is needed, Pass 2 reads specific book files from local disk — no GitHub API calls
+- Updated `HELP_QUERY.md` template to accept catalog + book content instead of flat documentation
+- Replaced `NEED_MORE_CONTEXT: file1, file2` protocol with structured `ANSWER:` / `BOOKS:` response format
+- Updated `report-issue` flow to use internal `_readPackageFile()` helper instead of the removed `readClaudeMd()`
+- Updated unit tests to cover two-pass librarian flow, catalog mocking, and book-read scenarios
+
+### 🔒 Security
+- Added path traversal protection when reading LLM-requested book paths — resolved paths are verified against the package root before disk access
+
+### 🗑️ Removed
+- Removed GitHub API dependency (`fetchFileContent`, `parseGitHubRepo`) from AI help flow — all context is now read from local disk
+- Removed `readClaudeMd()` single-file reader in favor of `readLibraryCatalog()` multi-file catalog builder
+
+
 ## [2.43.0] - 2026-04-30
 
 ### ✨ Added

package/README.md

@@ -295,7 +295,7 @@ claude-hooks telemetry clear  # Clear data
 ### Help & Issue Reporting
 
 ```bash
-claude-hooks help "how do presets work?"  # AI-powered help (uses CLAUDE.md)
+claude-hooks help "how do presets work?"  # AI-powered help (navigates .library/)
 claude-hooks help --report-issue          # Interactive GitHub issue creation
 claude-hooks --help                       # Static command reference
 ```
@@ -355,7 +355,7 @@ claude-hooks update   # Update to latest version
 | `debug.js`              | **Debug toggle** - enable/disable verbose logging                 | `runSetDebug()`                                                               |
 | `telemetry-cmd.js`      | **Telemetry commands** - show/clear statistics                    | `runShowTelemetry()`, `runClearTelemetry()`                                   |
 | `diff-batch-info.js`    | **Batch info** - orchestration config + per-model speed telemetry | `runDiffBatchInfo()`                                                          |
-| `help.js`               | **Help, AI help, report-issue**                                   | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()`                       |
+| `help.js`               | **Help, AI librarian, report-issue**                              | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()`                       |
 
 ### Utility Modules (`lib/utils/`)
 

package/lib/commands/help.js

@@ -4,7 +4,7 @@
  *
  * Features:
  * - Dynamic help from command registry (no args, --help, -h)
- * - AI help: routes questions to Claude with CLAUDE.md as knowledge base
+ * - AI help: two-pass librarian navigating .library/ for answers
  * - Report issue: interactive issue creation guided by Claude
  */
 
@@ -160,59 +160,130 @@ function printAiResponse(response, source) {
     console.log('');
 }
 
+/** Package root directory — resolved once from __dirname */
+const _packageRoot = path.join(__dirname, '..', '..');
+
 /**
- * Read CLAUDE.md from package root
- * Why: CLAUDE.md is the primary knowledge source shipped with the npm package
+ * Catalog directories within .library/ to auto-discover
+ * Why: These contain index and shelf files that form the navigational catalog.
+ * books/ is excluded — those are fetched on-demand in Pass 2.
+ */
+const _CATALOG_DIRS = ['by-code', 'by-domain', 'by-task-type'];
+
+/**
+ * Read a single file from package root, returning null on failure
  *
- * @returns {Promise<string|null>} CLAUDE.md content or null
+ * @param {string} relativePath - Path relative to package root
+ * @returns {Promise<string|null>} File content or null
  */
-const readClaudeMd = async () => {
-    const claudeMdPath = path.join(__dirname, '..', '..', 'CLAUDE.md');
+const _readPackageFile = async (relativePath) => {
     try {
-        const content = await fs.readFile(claudeMdPath, 'utf8');
-        logger.debug('help - readClaudeMd', 'CLAUDE.md loaded', { length: content.length });
-        return content;
-    } catch (error) {
-        logger.debug('help - readClaudeMd', 'CLAUDE.md not found', {
-            path: claudeMdPath,
-            error: error.message
-        });
+        return await fs.readFile(path.join(_packageRoot, relativePath), 'utf8');
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * 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)
+ *
+ * @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}`);
+            }
+        }
+    }
+
+    if (sections.length === 0) {
+        logger.debug('help - readLibraryCatalog', 'No catalog files found');
         return null;
     }
+
+    const catalog = sections.join('\n\n');
+    logger.debug('help - readLibraryCatalog', 'Catalog loaded', {
+        sections: sections.length,
+        length: catalog.length
+    });
+    return catalog;
 };
 
 /**
- * AI-powered help: routes question to Claude with CLAUDE.md context
- * Why: Provides intelligent answers about claude-hooks based on documentation
+ * AI-powered help: two-pass librarian navigating .library/
+ * Why: Provides intelligent answers by reading the project catalog, then
+ * fetching specific books from local disk only when deeper detail is needed.
  *
  * Flow:
- * 1. Read CLAUDE.md from package root
- * 2. Load HELP_QUERY.md template
- * 3. Call Claude with 30s timeout
- * 4. If NEED_MORE_CONTEXT: fetch referenced files from GitHub, re-query
- * 5. Display response
- * 6. On any error: fall back to static help
+ * 1. Read catalog from .library/ (auto-discovered indexes + shelves)
+ * 2. Pass 1: Send catalog to Claude via HELP_NAVIGATE.md
+ * 3. If ANSWER: display directly (1 Claude call)
+ * 4. If BOOKS: read requested books from local disk, send to HELP_QUERY.md (2 Claude calls)
+ * 5. On any error: fall back to static help
  *
  * @param {string} question - User's natural language question
  */
 async function runAiHelp(question) {
     try {
-        const claudeMdContent = await readClaudeMd();
-        if (!claudeMdContent) {
+        const catalog = await readLibraryCatalog();
+        if (!catalog) {
             logger.debug(
                 'help - runAiHelp',
-                'CLAUDE.md not available, falling back to static help'
+                'Catalog not available, falling back to static help'
             );
             showStaticHelp();
             return;
         }
 
-        const prompt = await loadPrompt('HELP_QUERY.md', {
-            DOCUMENTATION: claudeMdContent,
+        const prompt = await loadPrompt('HELP_NAVIGATE.md', {
+            CATALOG: catalog,
             QUESTION: question
         });
 
-        logger.debug('help - runAiHelp', 'Querying Claude', { questionLength: question.length });
+        logger.debug('help - runAiHelp', 'Querying Claude (Pass 1)', {
+            questionLength: question.length
+        });
         console.log('\nSearching documentation...\n');
 
         const pkg = getPackageJson();
@@ -221,95 +292,98 @@ async function runAiHelp(question) {
         const response = await executeClaudeWithRetry(prompt, { timeout: 60000 });
         const trimmedResponse = response.trim();
 
-        // Check for NEED_MORE_CONTEXT second pass
-        const needMoreLine = trimmedResponse
-            .split('\n')
-            .find((l) => l.includes('NEED_MORE_CONTEXT'));
-        if (needMoreLine) {
-            const enrichedResponse = await handleNeedMoreContext(
-                needMoreLine,
+        // Check for BOOKS: second pass
+        const booksLine = trimmedResponse.split('\n').find((l) => l.startsWith('BOOKS:'));
+        if (booksLine) {
+            const enrichedAnswer = await readAndAnswerWithBooks(
+                booksLine,
                 question,
-                claudeMdContent
+                catalog
             );
-            if (enrichedResponse) {
-                printAiResponse(enrichedResponse, `${localVersion} + source`);
-                return;
-            }
-            // Enrichment failed: show first-pass answer with marker line stripped
-            const cleanResponse = trimmedResponse
-                .split('\n')
-                .filter((l) => !l.includes('NEED_MORE_CONTEXT'))
-                .join('\n')
-                .trim();
-            if (cleanResponse) {
-                printAiResponse(cleanResponse, localVersion);
+            if (enrichedAnswer) {
+                printAiResponse(enrichedAnswer, `${localVersion} + source`);
                 return;
             }
+            // Books not readable — avoid surfacing raw BOOKS: line to the user
+            showStaticHelp();
+            return;
         }
 
-        printAiResponse(trimmedResponse, localVersion);
-    } catch (error) {
+        // ANSWER: response or fallback — strip the "ANSWER:" prefix if present
+        const answerLine = trimmedResponse.indexOf('ANSWER:');
+        const answer =
+            answerLine !== -1
+                ? trimmedResponse.substring(answerLine + 'ANSWER:'.length).trim()
+                : trimmedResponse;
+
+        printAiResponse(answer, localVersion);
+    } catch (err) {
         logger.debug('help - runAiHelp', 'AI help failed, falling back to static help', {
-            error: error.message
+            error: err.message
         });
         showStaticHelp();
     }
 }
 
 /**
- * Handle NEED_MORE_CONTEXT response by fetching referenced files from GitHub
+ * Pass 2: Read requested books from local disk and answer with enriched context
  *
- * @param {string} needMoreLine - The line containing NEED_MORE_CONTEXT marker
+ * @param {string} booksLine - The line starting with "BOOKS:" containing comma-separated paths
  * @param {string} question - Original user question
- * @param {string} claudeMdContent - Original CLAUDE.md content
- * @returns {Promise<string|null>} Enriched response or null on failure
+ * @param {string} catalog - The catalog content from Pass 1
+ * @returns {Promise<string|null>} Enriched answer or null on failure
  */
-async function handleNeedMoreContext(needMoreLine, question, claudeMdContent) {
+async function readAndAnswerWithBooks(booksLine, question, catalog) {
     try {
-        // Parse file paths from line: "NEED_MORE_CONTEXT: file1.js, file2.js"
-        const pathsPart = needMoreLine.replace('NEED_MORE_CONTEXT', '').replace(':', '').trim();
-        const filePaths = pathsPart
+        const pathsPart = booksLine.replace('BOOKS:', '').trim();
+        const bookPaths = pathsPart
             .split(',')
             .map((p) => p.trim())
             .filter(Boolean);
 
-        if (filePaths.length === 0) {
-            logger.debug('help - handleNeedMoreContext', 'No file paths in NEED_MORE_CONTEXT');
+        if (bookPaths.length === 0) {
+            logger.debug('help - readAndAnswerWithBooks', 'No book paths in BOOKS line');
             return null;
         }
 
-        logger.debug('help - handleNeedMoreContext', 'Fetching additional files', { filePaths });
-
-        const { owner, repo } = getSourceRepo();
-
-        // Fetch files in parallel (no ref = default branch, avoids 404 on unreleased tags)
-        const fetchResults = await Promise.all(
-            filePaths.map(async (filePath) => {
-                const content = await fetchFileContent(owner, repo, filePath);
-                return { filePath, content };
+        logger.debug('help - readAndAnswerWithBooks', 'Reading books from disk', { bookPaths });
+
+        // Read books from local filesystem in parallel
+        // Contain LLM-sourced paths to the package root to prevent traversal
+        const readResults = await Promise.all(
+            bookPaths.map(async (bookPath) => {
+                const resolvedPath = path.resolve(_packageRoot, bookPath);
+                if (!resolvedPath.startsWith(_packageRoot + path.sep)) {
+                    logger.debug('help - readAndAnswerWithBooks', 'Path traversal blocked', { bookPath });
+                    return { bookPath, content: null };
+                }
+                const content = await _readPackageFile(bookPath);
+                return { bookPath, content };
             })
         );
 
-        // Build enriched documentation
-        const additionalContent = fetchResults
+        const bookContent = readResults
             .filter((r) => r.content !== null)
-            .map((r) => `\n--- Source: ${r.filePath} ---\n${r.content}`)
-            .join('\n');
+            .map((r) => `--- ${r.bookPath} ---\n${r.content}`)
+            .join('\n\n');
 
-        if (!additionalContent) {
-            logger.debug('help - handleNeedMoreContext', 'No additional content fetched');
+        if (!bookContent) {
+            logger.debug('help - readAndAnswerWithBooks', 'No book content read from disk');
             return null;
         }
 
         const enrichedPrompt = await loadPrompt('HELP_QUERY.md', {
-            DOCUMENTATION: `${claudeMdContent}\n\n=== ADDITIONAL SOURCE FILES ===\n${additionalContent}`,
+            CATALOG: catalog,
+            BOOKS: bookContent,
             QUESTION: question
         });
 
         const enrichedResponse = await executeClaudeWithRetry(enrichedPrompt, { timeout: 60000 });
         return enrichedResponse.trim();
-    } catch (error) {
-        logger.debug('help - handleNeedMoreContext', 'Enrichment failed', { error: error.message });
+    } catch (err) {
+        logger.debug('help - readAndAnswerWithBooks', 'Book enrichment failed', {
+            error: err.message
+        });
         return null;
     }
 }
@@ -371,8 +445,8 @@ async function runReportIssue() {
             return;
         }
 
-        // Step 5: Read CLAUDE.md for project context
-        const claudeMdContent = await readClaudeMd();
+        // Step 5: Read CLAUDE.md for project context (report-issue only needs basic context)
+        const claudeMdContent = await _readPackageFile('CLAUDE.md');
 
         // Step 6: Generate questions from template using Claude
         const questionsPrompt = await loadPrompt('HELP_REPORT_ISSUE.md', {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.43.0",
+    "version": "2.44.0",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {

package/templates/HELP_NAVIGATE.md

@@ -0,0 +1,41 @@
+You are the claude-hooks CLI assistant.
+Answer the user's question using the project catalog provided below.
+
+The catalog contains:
+- CLAUDE.md: Global rules and restrictions
+- .library/index.md: Repo identity, capabilities, directory structure
+- .library/conventions.md: Coding standards and testing patterns
+- .library/by-code/ shelves: Source file indexes (maps file paths to book references)
+- .library/by-domain/ shelves: Business workflow reading lists
+- .library/by-task-type/ shelves: Task-specific guidance
+
+You must respond in EXACTLY ONE of two formats:
+
+FORMAT 1 — You CAN answer fully from the catalog:
+Start your response with "ANSWER:" on its own line, then provide the answer.
+Be concise, practical, and include command examples when relevant.
+Format for terminal output (no markdown headers, use indentation).
+
+ANSWER:
+[your complete answer here]
+
+FORMAT 2 — You need to read specific book files for a deep-dive answer:
+Start your response with "BOOKS:" followed by comma-separated .library/books/*.md paths.
+Pick ONLY the books that are directly relevant — do not request more than 5.
+The book paths are referenced in the by-code shelf files (look for @books/... references).
+
+BOOKS: .library/books/analysis-engine.md, .library/books/claude-client.md
+
+RULES:
+- Most questions about commands, workflows, configuration, and usage are answerable from the catalog (use FORMAT 1).
+- Only use FORMAT 2 for questions about internal implementation details (e.g., "how does analyzeCode retry on failure").
+- Do NOT include any text before the ANSWER: or BOOKS: line.
+- Do NOT combine both formats.
+
+---
+CATALOG:
+
+{{CATALOG}}
+
+---
+Question: {{QUESTION}}

package/templates/HELP_QUERY.md

@@ -1,23 +1,19 @@
 You are the claude-hooks CLI assistant.
-Answer the user's question based ONLY on the documentation provided below.
+Answer the user's question based on the project catalog and source book content provided below.
 Be concise, practical, and include command examples when relevant.
 Format for terminal output (no markdown headers, use indentation).
 
-IMPORTANT: You must choose exactly ONE of two response modes:
+The catalog gives you the project overview. The book content gives you the deep implementation details you need to answer this specific question.
 
-MODE 1 - You CAN answer from the documentation:
-  Respond directly with the answer. Do NOT include "NEED_MORE_CONTEXT" anywhere.
+---
+CATALOG:
 
-MODE 2 - You CANNOT answer accurately from the documentation alone:
-  Respond with ONLY a single line in this exact format (nothing else before or after):
-  NEED_MORE_CONTEXT: file1.js, file2.js
-  List the source file paths from the documentation that would contain the answer.
-  Do NOT include any explanation, apology, or partial answer. Just the single line.
+{{CATALOG}}
 
 ---
-DOCUMENTATION:
+BOOK CONTENT:
 
-{{DOCUMENTATION}}
+{{BOOKS}}
 
 ---
 Question: {{QUESTION}}