claude-git-hooks 2.35.3 → 2.44.0

package/CHANGELOG.md

@@ -5,6 +5,163 @@ 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
+- Headless mode for git hooks via CLAUDE_HOOKS_HEADLESS=1 environment variable, routing all LLM calls through the Anthropic SDK instead of the Claude CLI for CI/ECS environments (CT-805)
+- Unit tests for pre-commit and prepare-commit-msg hooks covering headless mode propagation and error messaging (CT-805)
+
+### 🔧 Changed
+- Hook error messages now show SDK-specific guidance ("Check that ANTHROPIC_API_KEY is set") in headless mode and CLI-specific guidance otherwise (CT-805)
+- Headless flag propagated through full analysis chain: runAnalysis, orchestrateBatches, judgeAndFix, and analyzeCode all accept and forward the headless option (CT-805)
+
+### 🐛 Fixed
+- Cross-platform path separator handling in hooks-verified marker test (#150)
+- Contract documentation test updated to match current CLAUDE.md section heading (#150)
+
+
+## [2.42.0] - 2026-04-30
+
+### ✨ Added
+- Added `Hooks-Verified: true` Git trailer to commits that pass pre-commit analysis, coordinated via a tree-SHA marker file in `.git/` (CT-802)
+- Added `hooks-verified-marker.js` utility for marker file CRUD between pre-commit (writes) and prepare-commit-msg (reads/validates/consumes)
+- Added `getStagedTreeSha()`, `hasHooksVerifiedTrailer()`, and `appendTrailer()` to git-operations for tree fingerprinting and canonical trailer formatting via `git interpret-trailers`
+- Added hooks-verified marker writing to the `analyze` command when staged-scope analysis completes without critical/blocker issues (CT-802)
+
+### 🔧 Changed
+- Reorganized CLAUDE.md project documentation into `.library/` structure with indexed books, shelves, and domain reading lists (#149)
+- Updated commit-workflow domain reading list and hook books to document the new Hooks-Verified trailer pipeline
+
+### 🐛 Fixed
+- Deferred trailer append in prepare-commit-msg until the final message is written, preventing the auto-generated message flow from overwriting the `Hooks-Verified` trailer (CT-802)
+
+
+## [2.41.1] - 2026-04-30
+
+### ✨ Added
+- Added headless mode and JSON output support for `analyze`, `create-pr`, and `lint` commands (#148, CT-799)
+
+### 🔧 Changed
+- Redistributed CLAUDE.md content into `.library/` — new `conventions.md` coding standards reference, enriched book indexes with key exports, and expanded domain quick-reference tables
+
+
+## [2.41.0] - 2026-04-30
+
+### ✨ Added
+- Added `--headless` flag to `analyze`, `create-pr`, and `lint` commands for non-interactive CI execution (CT-799)
+- Added `--format json` output mode that emits a single structured JSON line to stdout, routing all other output to stderr (CT-799)
+- Added `CostTracker` integration in headless mode for `analyze` and `create-pr` to report Claude API costs in JSON output (CT-799)
+- Added exit code 2 for usage errors (e.g., `--format json` without `--headless`) across `analyze`, `create-pr`, and `lint` (CT-799)
+- Added early fatal guard for detached HEAD state in `create-pr` with actionable fix instructions (CT-804, #147)
+
+### 🔧 Changed
+- Updated `interactive-ui.js` display helpers (`showSuccess`, `showError`, `showWarning`, `showInfo`) to delegate to `logger.js`, enabling JSON mode output routing to stderr
+- Updated `displayLintResults` to accept a `{ silent }` option that suppresses decorative output in JSON mode
+- Updated `create-pr` headless mode to resolve all 11 interactive decision points with documented defaults (auto-push, squash for unknown strategy, skip tag prompts)
+
+
+## [2.40.0] - 2026-04-30
+
+### ✨ Added
+- Added early detached HEAD detection in `create-pr` command with actionable error message and remediation steps (CT-804)
+- Added Operational Contract documentation in CLAUDE.md defining runtime environment requirements for CI/container orchestrators
+- Added CWD & Branch Contract reference book (`.library/books/cwd-contract.md`) with command-level HEAD tolerance matrix
+- Added smoke tests to prevent accidental deletion of contract documentation
+
+### 🔧 Changed
+- Moved branch detection earlier in `create-pr` flow (before interactive prompts) to fail fast on detached HEAD
+- Replaced `error()` + `return` with `fatal()` for detached HEAD guard in `create-pr`, ensuring consistent process termination
+
+
+## [2.39.0] - 2026-04-29
+
+### ✨ Added
+- Added `--headless` flag to `install` command for CI/container environments — skips all side effects: dependency checks, git config, `.gitignore` updates, shell completions, linter availability check, and GitHub token setup (CT-803)
+- Added `--verify-sdk` flag to `install` command — opt-in 1-token SDK ping (haiku, 10s timeout) to validate `ANTHROPIC_API_KEY` after installation; exits 1 in headless mode on failure, warns in interactive mode (CT-803)
+- Added `verifySDKConnection()` to `claude-client.js` — minimal SDK connectivity check that delegates to `_executeSDK('ping')` and never throws (CT-803)
+- Added `--headless` bypass for authorization guard in CLI router — CI runners skip RBAC checks entirely; governance enforced at branch-protection level (CT-803)
+
+### 🔧 Changed
+- Install orchestration expanded from 20 to 21 steps to accommodate the new SDK verification step
+
+### ⚠️ Deprecated
+- Deprecated `--skip-auth` flag on `install` command — use `--headless` instead for full CI/container mode; logs a deprecation warning when used
+
+
+## [2.38.0] - 2026-04-29
+
+### ✨ Added
+- Added headless mode (`--headless`) for `analyze-pr` command — skips all interactive prompts for CI/automation pipelines
+- Added JSON output mode (`--format json`) for `analyze-pr` — emits a single structured JSON document to stdout with verdict, severity counts, comments, and cost data (requires `--headless`)
+- Added cost tracking for headless `analyze-pr` runs via `CostTracker` integration (#144)
+- Added Langfuse trace flushing after headless SDK calls for observability (#144)
+- Added `fatal()` function to helpers.js for process-terminating errors, separating logging from exit behavior
+- Added JSON mode to logger (`setJSONMode`) — routes `info`/`success`/`warning`/`debug` to stderr, reserving stdout for structured output
+
+### 🔧 Changed
+- Changed `error()` in helpers.js to log-only (no longer calls `process.exit`) — callers needing termination should use `fatal()` instead
+- Changed `bin/claude-hooks` to use `fatal()` for unknown command errors
+- Changed `helpers.info()`, `helpers.success()`, and `helpers.warning()` to delegate to logger equivalents, respecting JSON mode routing
+
+
+## [2.37.0] - 2026-04-29
+
+### ✨ Added
+- Added cost tracking for headless SDK calls — per-call USD cost calculation with cache token multipliers, hardcoded Anthropic pricing table, and CloudWatch-friendly structured JSON logs (`cost-tracker.js`)
+- Added optional Langfuse tracing integration for headless SDK calls — records LLM generations (model, tokens, cost, prompt/response) as traces; disabled by default, activated via `LANGFUSE_ENABLED` env var (`langfuse-tracer.js`)
+- Added `costTracker` option to `analyzeCode()`, `executeClaudeWithRetry()`, and `executeClaude()` for external cost accumulation across multiple calls
+- Added `._costs` field to `analyzeCode()` results in headless mode — contains per-call token usage and USD cost snapshot
+
+### 🔧 Changed
+- Changed `_executeSDK()` return type from plain text string to `{ text, usage, model }` — callers now receive normalized token usage and resolved model ID
+- Normalized SDK usage fields with defaults (0 for missing cache token counts) to ensure consistent downstream processing
+- Updated library documentation with new books for `cost-tracker.js` and `langfuse-tracer.js`, updated `claude-client.js` book with observability details
+
+
+## [2.36.0] - 2026-04-28
+
+### ✨ Added
+- Added SDK adapter for headless mode in claude-client — dual execution backend: CLI spawn for local/interactive use, or Anthropic SDK direct calls for headless/ECS environments (#141)
+- Added `_executeSDK()` function for direct Anthropic SDK calls with lazy-loaded `@anthropic-ai/sdk` dependency
+- Added `resolveModelAlias()` and `MODEL_ALIASES` constant with environment variable overrides (`CLAUDE_MODEL_SONNET`, `CLAUDE_MODEL_OPUS`, `CLAUDE_MODEL_HAIKU`)
+- Added `headless` option to `analyzeCode()`, `executeClaudeWithRetry()`, and `executeClaude()` for SDK-based execution
+- Added `claude.defaultModel` to hardcoded config as fallback model for SDK headless mode
+
+### 🔧 Changed
+- Changed `analyzeCode()` to return parsed JSON object instead of raw response text
+- Changed `executeClaude()` to branch between SDK path (when `headless: true`) and CLI spawn path
+- SDK errors marked with `fromSDK: true` are no longer retried by `withRetry` — the Anthropic SDK already retries internally (2 attempts for rate limits, timeouts, and 5xx)
+- Updated claude-client library book to document dual-backend architecture, SDK gotchas, and new exports
+
+### 🐛 Fixed
+- Fixed Spotless timeouts and cmd.exe per-file mode (#141)
+
+### 🗑️ Removed
+- Removed `.library/CATEGORY_COMPLETENESS_REPORT.md` and `.library/CLASSIFICATION_REPORT.md` reports
+
+
 ## [2.35.3] - 2026-04-22
 
 ### ✨ Added