claude-git-hooks 2.45.0 → 2.61.2

package/CHANGELOG.md

@@ -5,40 +5,377 @@ 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.61.2] - 2026-06-01
+
+### 🐛 Fixed
+- Fixed incorrect import path for gotcha solicitation in PR pipeline
+
+
+## [2.61.1] - 2026-06-01
+
+### ✨ Added
+- Auto-regeneration of stale Library books during `create-release` — stale books are now regenerated before the release is tagged, keeping the tag accurate (#178, AUT-3738)
+
+### 🔧 Changed
+- Staleness warning templates are now context-aware: `CONSOLE_WARNING_TEMPLATE` and `PR_BODY_SECTION_TEMPLATE` accept an `autoRegen` option to tailor messaging per consumer (`will-run` for create-release, `deferred` for bump-version, `completed`/`failed` in PR body)
+- PR body staleness section now reflects the actual auto-regeneration outcome instead of always listing remediation scripts
+- Console staleness warning in `bump-version` now tells the user that Library will be auto-regenerated when they run `create-pr`
+
+### 🗑️ Removed
+- Removed static recommended-scripts list from console staleness warnings (replaced by context-aware auto-regeneration messages)
+
+
+## [2.61.0] - 2026-06-01
+
+### ✨ Added
+- Added canonical staleness-warning templates (`CONSOLE_WARNING_TEMPLATE`, `PR_BODY_SECTION_TEMPLATE`, `PR_TAG_VALUE`) for consistent Library staleness messaging across all consumer commands (AUT-3738)
+- Added non-blocking Library staleness verification gate to the `create-release` workflow — warns operators when Library books are out of date without blocking the release (AUT-3738)
+- Added automatic release PR creation step in `create-release` with idempotency check, staleness section in PR body wrapped in marker comments, and `library-stale` label when applicable (AUT-3738)
+- Added `LIBRARY_VERIFY_SKIPPED_WARNING_RELEASE` constant for release-specific Library verification skip messaging (AUT-3738)
+
+### 🔧 Changed
+- Refactored `bump-version` Library warning to use the canonical `CONSOLE_WARNING_TEMPLATE` instead of inline formatting (AUT-3738)
+- Changed `create-release` Library staleness gate from blocking (exit on stale) to non-blocking (warn and continue), using the librarian `verify()` API instead of raw staleness tools (AUT-3738)
+- Refactored `library-warnings.js` to re-export canonical wording from the librarian messages module instead of defining constants inline (AUT-3738)
+- Updated Library books for `create-release`, `bump-version`, and `library-warnings` to reflect new dependencies and exports (AUT-3738)
+
+### 🗑️ Removed
+- Removed blocking Library staleness check from `create-release` that imported `.library/tools/staleness.js` directly and aborted on drift (AUT-3738)
+- Removed `LIBRARY_STALE_WARNING` constant from `library-warnings.js`, replaced by canonical `CONSOLE_WARNING_TEMPLATE` (AUT-3738)
+
+
+## [2.61.0] - 2026-05-29
+
+### ✨ Added
+
+- Added gotcha solicitation orchestrator for the Library system, enabling interactive developer prompts to capture known gotchas per book during the create-pr pipeline (AUT-3735)
+- Added end-to-end cross-cutting tests for the gotcha solicitation flow covering manual-additions preservation and API-down graceful degradation (AUT-3735)
+- Added Library verification gate for the bump-version workflow with warning constants in `library-warnings.js` (#176, AUT-3737)
+
+### 🔧 Changed
+
+- Updated bump-version book to reference the new `library-warnings.js` dependency (AUT-3737)
+
+## [2.60.0] - 2026-06-01
+
+### ✨ Added
+
+- Added canonical staleness-warning templates (`CONSOLE_WARNING_TEMPLATE`, `PR_BODY_SECTION_TEMPLATE`, `PR_TAG_VALUE`) for consistent Library staleness messaging across all consumer commands (AUT-3738)
+- Added non-blocking Library staleness verification gate to the `create-release` workflow — warns operators when Library books are out of date without blocking the release (AUT-3738)
+- Added staleness section to release PR body when Library is stale, wrapped in marker comments for downstream tooling (AUT-3738)
+
+### 🔧 Changed
+
+- Refactored `bump-version` Library warning to use the canonical `CONSOLE_WARNING_TEMPLATE` instead of inline formatting (AUT-3738)
+- Updated Library books for `create-release`, `bump-version`, and `library-warnings` to reflect new dependencies and exports (AUT-3738)
+
+### 🗑️ Removed
+
+- Removed gotcha solicitation orchestrator (`gotcha-solicitation.js`) from the Library system (AUT-3738)
+
+## [2.59.0] - 2026-05-29
+
+### ✨ Added
+
+- Library verification gate in `bump-version` command — warns about stale or missing Library books before proceeding with version bump (AUT-3737)
+- Read-only `verify()` staleness check to librarian module with never-throws guarantee (AUT-3737)
+- Warning wording constants for Library verification gates in `lib/messages/library-warnings.js` (AUT-3737)
+- `updatePullRequestBody()` method to GitHub API utility (#175)
+
+### 🔧 Changed
+
+- Back-merge co-change pipeline "skipped" message now uses `logger.warning` instead of raw stderr write (#175)
+- Library books synced for back-merge and github-api modules (#175)
+
+## [2.58.0] - 2026-05-29
+
+### ✨ Added
+
+- Integrated co-change correlation pipeline into back-merge workflow — runs 6-step detection, mode resolution, sidecar write, injection, and report generation after merge commit (AUT-3777)
+- Added `updatePullRequestBody()` to GitHub API module for updating PR body content
+- Auto-attach co-change analysis report to back-merge PR body with idempotent marker comments for safe re-runs (AUT-3777)
+- Added comprehensive smoke tests for back-merge co-change pipeline glue
+
+### 🔧 Changed
+
+- Back-merge co-change step now uses `coChangePipeline()` orchestrator instead of the standalone `inject-co-change.js` tool — stages and commits Library changes as a separate `chore(library)` commit
+- Updated Library README with full `coChangePipeline()` documentation including sequence diagram, consumer contract, mode reference, and limitations
+
+### 🐛 Fixed
+
+- Fixed false-positive linter warnings (#174)
+
+### 🗑️ Removed
+
+- Removed legacy `inject-co-change.js` tool invocation from back-merge post-push step, replaced by integrated pipeline
+
+## [2.57.1] - 2026-05-29
+
+### 🐛 Fixed
+
+- Filtered ESLint meta-warnings for ignored files that produced false-positive linter output
+- Fixed co-change pipeline injection result not being captured when running in inject mode
+
+### 🗑️ Removed
+
+- Removed `createPrPipeline()` Library maintenance orchestrator and associated M6 documentation
+
+## [2.57.0] - 2026-05-28
+
+### ✨ Added
+
+- Added `createPrPipeline()` 5-step Library maintenance orchestrator for the `create-pr` command — runs staleness detection, auto-section regeneration, book add/remove/rename, frontmatter sync, and gotcha solicitation sequentially (AUT-3736)
+- Added comprehensive pipeline documentation to Library README including sequence diagram, consumer contract, and return shape
+
+### 🔧 Changed
+
+- Integrated Library maintenance pipeline into `create-pr` command — now triggers full book sync instead of only reporting staleness (AUT-3736)
+- Updated Library milestone status: M5 (core hypothesis validation) marked as shipped, M6 (lifecycle automation) added as in-progress
+- Removed unused variables in `co-change-pipeline.js` (`injectionResult`), `cross-ref-injector.js` (`fileContents`), and renamed unused parameter in `gotcha-persistence.js` (`opts` → `_opts`)
+- Replaced string concatenation with template literals in `gotcha-persistence.js`
+
+## [2.56.0] - 2026-05-28
+
+### ✨ Added
+
+- Added candidate gotcha text generator for librarian books — calls Claude API to propose non-obvious tribal knowledge from PR descriptions, commit messages, and source comments (AUT-3735)
+- Added gotcha persistence module for appending accepted gotchas below the manual-additions separator in book files, with idempotency and frontmatter flagging when the API is unreachable (AUT-3735)
+- Added co-change analysis pipeline (#170)
+
+## [2.55.0] - 2026-05-27
+
+### ✨ Added
+
+- Added co-change detector that parses git history within a configurable window, computes co-occurrence weighted edges between file pairs, and filters by confidence thresholds (AUT-3740)
+- Added cross-reference injector that updates book frontmatter with co-change cross-references, supporting bidirectional refs for regular books and directional used_by refs for utility books (AUT-3740)
+- Added co-change pipeline orchestrator that runs the full 5-step sequence: detection, mode resolution, sidecar write, optional injection, and markdown analysis report generation (AUT-3740)
+- Added comprehensive unit and idempotency tests for co-change pipeline and cross-ref injector (AUT-3740)
+
+### 🔧 Changed
+
+- Replaced string concatenation with template literal in co-change-mode sidecar writer (lint fix)
+
+## [2.54.1] - 2026-05-27
+
+### ✨ Added
+
+- Added comprehensive test suite for librarian console API covering isTTY, selectOne, selectMany, confirm, and freeText functions (AUT-3756)
+- Added gotcha solicitation usage example demonstrating the console API interactive workflow (AUT-3756)
+
+## [2.54.0] - 2026-05-27
+
+### ✨ Added
+
+- Co-change mode dispatcher for the back-merge pipeline with two modes: `collect-only` (edge accumulation) and `inject` (cross-reference writing), with automatic transition after a configurable threshold of 5 back-merges (AUT-3772)
+- Sidecar state file (`.library/maps/co-change-state.json`) for persisting co-change edges, back-merge counts, and transition configuration across pipeline runs
+- CLI override support (`--co-change-mode=collect-only|inject`) for per-invocation mode control without mutating sidecar state
+- Schema validation, append-only edge merging, and alphabetical edge normalization for deterministic sidecar diffs
+- Comprehensive unit tests for co-change mode dispatcher covering constants, validation, I/O, edge operations, mode resolution, and cold-start behavior
+
+### 🔧 Changed
+
+- Updated back-merge documentation to reflect co-change edge collection and conditional injection via mode dispatcher (#167)
+
+## [2.53.0] - 2026-05-27
+
+### ✨ Added
+
+- Added post-regen review pass that uses Claude CLI to suggest manual-section improvements based on auto-section changes (#166)
+- Added `--no-review` flag to `regenerate` and `report` commands to skip the Claude review step
+- Added `line-diff.js` — pure-function line-based diff utility for LLM consumption (no shell dependencies)
+- Added `llm.js` — thin Claude CLI wrapper with availability check and graceful degradation
+- Added `review-pass.js` — interactive review workflow: Accept / Edit / Skip / Skip-all per suggestion
+
+### 🔧 Changed
+
+- Enriched `regenerate()` output with `diff_context` (old/new auto-section, manual section, source file) for changed books
+- Updated `report` command to include the review pass as Step 2b in the full maintenance cycle
+- Renumbered execution prompt steps (overflow check → Step 4, gotcha solicitation → Step 5, report → Step 6) to accommodate the new review step
+
+## [2.52.0] - 2026-05-27
+
+### ✨ Added
+
+- Interactive console primitive for the librarian, enabling programmatic library access (AUT-3734)
+- Comprehensive I/O documentation, execution flows, cross-references, and gotchas for library books: analysis-engine, analyze-diff, analyze-pr, authorization, bump-version (AUT-3734)
+
+### 🔧 Changed
+
+- ESLint configuration now includes `.library/librarian/**` in linting scope
+
+### 🐛 Fixed
+
+- Fixed bump-version issue (#165)
+- Fixed inaccuracies in library book documentation (AUT-3734)
+
+## [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)
 
+- 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
 
+- Removed CLAUDE-MIGRATION.md — migration map no longer needed after library stabilization
 
 ## [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
@@ -47,56 +384,63 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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)
 
+- 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
 
+- 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)
@@ -104,42 +448,46 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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
 
+- 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)
@@ -148,28 +496,30 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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`)
@@ -177,21 +527,24 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - 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
 
+- Removed `.library/CATEGORY_COMPLETENESS_REPORT.md` and `.library/CLASSIFICATION_REPORT.md` reports
 
 ## [2.35.3] - 2026-04-22
 
 ### ✨ Added
+
 - Code Knowledge Library (`.library/`) with 25 reference books covering source modules — structured documentation with call signatures, I/O behavior, cross-references, and gotchas per module (#125-#131)
 - By-code index for navigating from source file paths to their reference books (`by-code/utils.md`, `by-code/commands.md`, `by-code/hooks.md`)
 - By-domain index with curated reading lists for four business workflows: commit pipeline, release management, PR analysis, and GitHub integration (`by-domain/`)
@@ -201,24 +554,26 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - Classification report and category completeness report validating all 66 source modules against the 8-category taxonomy
 
 ### 🐛 Fixed
-- Spotless linting timeouts and cmd.exe per-file mode on Windows — resolves batch-mode failures when Spotless wrapper is a `.cmd`/`.bat` file (#124, #125)
 
+- Spotless linting timeouts and cmd.exe per-file mode on Windows — resolves batch-mode failures when Spotless wrapper is a `.cmd`/`.bat` file (#124, #125)
 
 ## [2.35.2] - 2026-04-13
 
 ### ✨ Added
+
 - Added Maven Wrapper (mvnw/mvnw.cmd) auto-detection for Spotless — bypasses cmd.exe metacharacter issues on Windows/WSL2
 - Added per-file execution mode for Spotless to avoid pipe (`|`) metacharacter in regex arguments on Windows
 - Added `env` option to `runTool`, `runToolFix`, and `runToolWithAutoFix` for passing extra environment variables to tool invocations
 - Added `configDir` to `_detectInProjectFiles` return value for downstream Maven Wrapper resolution
 
 ### 🐛 Fixed
-- Fixed Spotless linter failing on Windows/WSL2 when multiple Java files are staged — `|` (pipe) in the `DspotlessFiles` regex was interpreted as a shell pipe by cmd.exe during batch script expansion
 
+- Fixed Spotless linter failing on Windows/WSL2 when multiple Java files are staged — `|` (pipe) in the `DspotlessFiles` regex was interpreted as a shell pipe by cmd.exe during batch script expansion
 
 ## [2.35.1] - 2026-04-08
 
 ### ✨ Added
+
 - Local binary resolution for linter tools — walks up from config directory to repo root, preferring project-installed binaries over npx to prevent version mismatches (#123)
 - Array-form `detectInProjectFile` for tool detection — Prettier and ESLint now recognized via config files (.prettierrc, .eslintrc.json, eslint.config.js, etc.) in addition to package.json dependencies
 - WSL2/Windows interop support for .cmd/.bat tool binaries, with proper cmd.exe metacharacter escaping
@@ -226,39 +581,43 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - New `localBin` and `toolCwd` options for `runTool`/`runToolFix`/`runToolWithAutoFix` enabling direct binary execution and correct plugin resolution in monorepos
 
 ### 🔧 Changed
+
 - Replaced `execSync` with `execFileSync` in tool-runner — args passed directly to process, preventing shell interpretation of regex metacharacters (e.g., `|` in Spotless patterns) and file path injection
 - Tool detection now requires project-level configuration when `detectInProjectFile` is defined — PATH-only presence no longer sufficient, preventing false positives (e.g., mvn in PATH treated as Spotless available)
 - Project file scanning starts from repo root instead of cwd, fixing detection when git hooks run from subdirectories
 - Increased judge timeout from 120s to 180s
 
 ### 🐛 Fixed
+
 - Fixed tool auto-fix being attempted after execution failures (ENOENT, EACCES) by tracking `executionFailed` flag and skipping fix step
 - Fixed ENOENT handling in `runToolFix` — missing command binary now returns gracefully instead of being misinterpreted as a partial fix
 - Fixed `git add` in restage step to use `execFileSync` with proper argument array instead of shell string interpolation
 
 ### 🔒 Security
+
 - Eliminated shell injection risk in tool execution by switching from `execSync` (shell-based) to `execFileSync` (direct process spawn)
 - Added `_escapeCmdMeta()` and `_prepareExec()` for safe cmd.exe argument passing when executing .cmd/.bat files on Windows/WSL
 
-
 ## [2.35.0] - 2026-03-27
 
 ### ✨ Added
+
 - Prettier formatting support — auto-formats JS/TS/CSS/HTML/JSON/YAML/MD files before linting (format first, then lint)
 - Remote formatter configuration — preset-to-tools mapping fetched from centralized git-hooks-config repo, allowing team-wide control without releasing new versions
 - New `parsePrettierOutput()` function for parsing Prettier --check output into structured issues
 
 ### 🔧 Changed
+
 - Linting pipeline now runs formatters (Prettier) before linters (ESLint) for consistent code style
 - Updated preset-to-tools mapping: frontend, fullstack, ai, and default presets now include Prettier
 - `getLinterToolsForPreset()` now fetches remote config with local fallback instead of using hardcoded mapping only
 - `runLinters()` and `checkLinterAvailability()` converted to async functions to support remote config fetching
 - Unfixable linting issues are now forwarded to the Claude judge for semantic resolution instead of blocking directly
 
-
 ## [2.34.0] - 2026-03-27
 
 ### ✨ Added
+
 - Pre-commit linting with ESLint, Spotless, and sqlfluff - runs before Claude analysis with auto-fix and re-stage
 - `lint` command - run linters on staged files, directories, or specific files (`claude-hooks lint [paths...]`)
 - Linter availability check during installation - verifies linter presence per preset and shows install instructions
@@ -267,30 +626,33 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - Maven availability check during installation with install instructions for backend/fullstack presets
 
 ### 🔧 Changed
+
 - Pre-commit flow now runs linting before Claude analysis - fast, deterministic checks first
 - Unfixable lint issues are forwarded to the judge for semantic resolution
 - Updated documentation to reflect new linting workflow and command usage
 
 ### 🐛 Fixed
-- WSL Claude CLI detection in non-default distros (#120, #121)
 
+- WSL Claude CLI detection in non-default distros (#120, #121)
 
 ## [2.33.1] - 2026-03-26
 
 ### 🔧 Changed
+
 - Improved WSL Claude CLI detection to resolve Claude's path via login shell when installed via nvm or user-scoped npm prefix
 - Added support for detecting Claude CLI in non-default WSL distros when the default distro is docker-desktop or similar
 - Switched to execFileSync for WSL distro listing to avoid cmd.exe quote mangling issues
 - Updated README-NPM with release workflow commands documentation and WSL troubleshooting guide
 
 ### 🐛 Fixed
+
 - Fixed Claude CLI not being detected on Windows when running from Git Bash with Claude installed inside WSL via nvm (#120)
 - Fixed WSL distro detection failing due to UTF-16LE encoding from wsl.exe output
 
-
 ## [2.33.0] - 2026-03-20
 
 ### ✨ Added
+
 - Always-on metrics system for code quality observability (#41) - collects structured JSONL events locally with 90-day retention for trend analysis
 - Team-based reviewer selection via GitHub Teams API (#115, #36) - automatically resolves team members and excludes PR author when selecting reviewers
 - New metrics module (`lib/utils/metrics.js`) with fire-and-forget event recording that never blocks callers
@@ -298,19 +660,21 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - Documented proven implementation patterns in CLAUDE.md covering testability, git operations, and architecture best practices
 
 ### 🔧 Changed
+
 - Telemetry system now always enabled - removed opt-out toggle for consistent observability
 - Existing telemetry events dual-write to unified metrics system for consolidated analysis
 - PR statistics module now records to both legacy JSONL and new metrics system
 - Judge module switched from telemetry to metrics recording with richer event data including false positives and unresolved issues
 
 ### 🗑️ Removed
+
 - Removed `system.telemetry` configuration option - metrics are now always collected locally
 - Removed telemetry disabled warnings from `batch-info` and `telemetry-cmd` commands
 
-
 ## [2.32.0] - 2026-03-19
 
 ### ✨ Added
+
 - Team-based reviewer selection using GitHub Teams API for Pull Requests (#36)
 - New `reviewer-selector.js` module for intelligent team member resolution with PR author exclusion
 - Support for `teamSlug` configuration in `config.github.pr` (defaults to 'automation')
@@ -318,6 +682,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - New GitHub API methods: `listRepoTeams()` and `listTeamMembers()` for team resolution
 
 ### 🔧 Changed
+
 - PR reviewer selection now prioritizes GitHub Teams API over CODEOWNERS file
 - Updated `createPullRequest()` to accept `teamReviewers` parameter for team-based review requests
 - Refactored `github-client.js` to focus on config-based fallback reviewers only
@@ -325,18 +690,18 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - Updated documentation to reflect team-based reviewer workflow in CLAUDE.md and README files
 
 ### 🗑️ Removed
+
 - CODEOWNERS file parsing and resolution logic from reviewer selection workflow
 - Methods `readCodeowners()` and `parseCodeownersReviewers()` from `github-client.js`
 
-
 ## [2.31.1] - 2026-03-19
 
 ### 🔧 Changed
+
 - Migrated authorization config repository from `claude-hooks-config` to `git-hooks-config` as the definitive source for permissions and labels
 - Centralized existing permissions and labels configuration in the definitive repository
 - Updated documentation in CLAUDE.md to reference the new `git-hooks-config` repository and document team-wide remote config pattern
 
-
 ## [2.31.0] - 2026-03-19
 
 ### ✨ Added