claude-git-hooks 2.35.3 → 2.43.0

package/CLAUDE.md

@@ -1,1400 +1,35 @@
 # Repository Context
 
-## Purpose
+`claude-git-hooks` — intelligent Git hooks system integrating Claude CLI for code analysis, commit message generation, PR creation, and release workflow automation.
 
-`claude-git-hooks` is an intelligent Git hooks system that integrates Claude CLI to automate code analysis, commit message generation, and PR creation. It functions as a pre-commit code quality tool (for pre-commit code quality checks) that blocks commits with critical issues and assists throughout the development workflow.
+## Context Acquisition
 
-**Main use cases:**
+All project knowledge lives in [`.library/`](.library/). Start at [`.library/index.md`](.library/index.md).
 
-1. **Pre-commit linting**: Runs formatters and linters (Prettier, ESLint, Spotless, sqlfluff) on staged files before Claude analysis — fast, deterministic, auto-fix enabled by default
-2. **Pre-commit analysis**: Detects security issues, bugs, and code smells before each commit (blocks on CRITICAL/BLOCKER only)
-3. **Interactive analysis**: `claude-hooks analyze` - review all issues (INFO to BLOCKER) interactively before committing
-4. **Automatic messages**: Write `git commit -m "auto"` and Claude generates the message in Conventional Commits format with task-id extracted from branch
-5. **PR analysis**: `claude-hooks analyze-diff [branch]` generates title, description, and test plan for PRs
-6. **PR review**: `claude-hooks analyze-pr <url>` analyzes a GitHub PR with preset guidelines, Linear ticket enrichment, and posts review comments
-7. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset, merge strategy auto-detected from branch naming)
-8. **Linting**: `claude-hooks lint [paths...]` runs formatters and linters on staged files, directories, or specific files — supports Prettier, ESLint, Spotless, sqlfluff per preset (remote config priority with local fallback)
-9. **Coupling detection**: `claude-hooks check-coupling` scans open PRs targeting a base branch, computes file overlap, and reports which features are coupled (share modified files) — helps TL make informed decisions before cutting a release
-10. **Shadow management**: `claude-hooks shadow <analyze|reset|sync>` manages the shadow branch lifecycle — analyze divergence vs main and active RC, reset shadow to a clean copy of main, or sync shadow with a source branch (RC, develop, feature)
-11. **Release creation**: `claude-hooks create-release <major|minor|patch>` creates a release-candidate branch from develop, bumps version files, commits, pushes, and deploys to shadow — replaces the 8 manual steps executed every Tuesday by the Tech Lead
-12. **Feature revert**: `claude-hooks revert-feature <task-id>` finds a squash-merged feature commit by task ID in the current release-candidate, checks coupling with other RC features, reverts it, pushes, and optionally re-deploys shadow
-13. **Release closure**: `claude-hooks close-release [description]` finalizes the active release-candidate — soft-resets onto main, creates a single clean commit, force-pushes, and creates a PR to main with the merge-commit strategy
+Load context based on your current task:
 
-## Architecture
+| 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 |
 
-### Technology Stack
+Books follow a standard template at `.library/templates/book-template.md`. After modifying a module, update its book and the relevant shelf index.
 
-- **Runtime**: Node.js >=16.9.0 (compatible up to 24+)
-- **Module type**: ES6 modules (`"type": "module"` in package.json)
-- **Main dependencies**:
-    - `@octokit/rest`: GitHub client for PR creation (v2.5.0+)
-- **Dev dependencies**: Jest, ESLint, Prettier
-- **Distribution**: NPM global package (`npm install -g claude-git-hooks`)
+## Global Rules
 
-### Design Philosophy
+These behavioral rules apply to all work in this repository:
 
-**Modular, decoupled, reusable code.** Each component has a single responsibility:
+1. **Do NOT perform git add, commit, or push unless explicitly asked** — git flow is handled by the human user
+2. **Do NOT add dependencies without justification** — only 1 runtime dep (`@octokit/rest`); verify no built-in alternative exists
+3. **Do NOT modify `.gitignore` without consultation** — `.claude/` is ignored by design
+4. **Do NOT commit secrets** — tokens go in `.claude/settings.local.json` (gitignored) or env vars, never in tracked files
+5. **Do NOT make breaking changes without MAJOR version bump** — config format, CLI arguments, template format changes require MAJOR
+6. **Do NOT hardcode absolute paths** — use `getRepoRoot()` from `git-operations.js`; all paths relative to repo root
+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()`
 
-- **bin/claude-hooks**: Thin CLI router - argument parsing, command dispatch, and authorization guard
-- **lib/commands/**: Command modules - one file per CLI command, self-contained logic
-- **lib/hooks/**: Git hook logic - Node.js implementations invoked by bash wrappers
-- **lib/utils/**: Reusable utilities - shared across commands, no CLI dependencies
-- **templates/**: Static assets - copied during installation, user-customizable
-
-This separation enables:
-
-- **Testability**: Each module can be unit tested independently
-- **Maintainability**: Changes to one command don't risk breaking others
-- **Discoverability**: Find code by filename matching command name
-- **Extensibility**: Add new commands by creating new module files
-
-### Directory Structure
-
-```
-claude-git-hooks/
-├── bin/
-│   └── claude-hooks                  # Thin CLI router - uses cli-metadata.js registry for dispatch
-├── lib/
-│   ├── cli-metadata.js               # Command registry - single source of truth for CLI commands, flags, descriptions
-│   ├── config.js                     # Config system - load/merge with priority
-│   ├── commands/                     # Command modules - one file per CLI command
-│   │   ├── helpers.js                # Shared CLI utilities - colors, output, platform
-│   │   ├── install.js                # Install command - dependencies, hooks, templates, linter check
-│   │   ├── hooks.js                  # Hook management - enable, disable, status, uninstall
-│   │   ├── analyze-diff.js           # Diff analysis - generate PR metadata from git diff
-│   │   ├── analyze-pr.js             # PR analysis - analyze GitHub PR with team guidelines
-│   │   ├── check-coupling.js         # Coupling detection - detect coupled PRs before release (v2.23.0)
-│   │   ├── shadow.js                 # Shadow management - analyze/reset/sync shadow branch lifecycle (v2.24.0)
-│   │   ├── create-release.js         # Release creation - RC branch from develop, version bump, shadow deploy (v2.27.0)
-│   │   ├── revert-feature.js         # Feature revert - find by task-id, coupling check, git revert, push, shadow (v2.28.0)
-│   │   ├── close-release.js          # Release closure - soft-reset, single commit, force-push, PR to main (v2.29.0)
-│   │   ├── create-pr.js              # PR creation - full Octokit workflow
-│   │   ├── setup-github.js           # Token setup - interactive GitHub configuration
-│   │   ├── setup-linear.js           # Token setup - interactive Linear configuration
-│   │   ├── presets.js                # Preset management - list, set, show current
-│   │   ├── update.js                 # Self-update - check and install latest version
-│   │   ├── migrate-config.js         # Config migration - legacy to v2.8.0 format
-│   │   ├── debug.js                  # Debug toggle - enable/disable verbose logging
-│   │   ├── telemetry-cmd.js          # Telemetry commands - show/clear statistics
-│   │   ├── bump-version.js           # Version management - bump with commit, CHANGELOG and tags
-│   │   ├── generate-changelog.js     # CHANGELOG generation - standalone command
-│   │   ├── diff-batch-info.js        # Batch info - orchestration config + speed telemetry (v2.20.0)
-│   │   ├── lint.js                    # Lint command - run linters on staged files, dirs, or files
-│   │   └── help.js                   # Help, AI help, and report-issue commands
-│   ├── hooks/                        # Git hooks - Node.js implementations
-│   │   ├── pre-commit.js             # Pre-commit analysis - code quality gate
-│   │   └── prepare-commit-msg.js     # Message generation - auto commit messages
-│   └── utils/                        # Reusable modules - shared logic
-│       ├── tool-runner.js            # Generic tool executor - resolve, spawn, parse, auto-fix (v2.34.0)
-│       ├── linter-runner.js          # Linter orchestration - preset mapping, Prettier/ESLint/Spotless/sqlfluff, remote config (v2.34.0)
-│       ├── analysis-engine.js        # Shared analysis logic - file data, 3-tier routing, results (v2.13.0+)
-│       ├── diff-analysis-orchestrator.js  # Intelligent batch orchestration via Opus (v2.20.0)
-│       ├── claude-client.js          # Claude CLI wrapper - spawn, retry, model override
-│       ├── prompt-builder.js         # Prompt construction - load templates, replace vars
-│       ├── git-operations.js         # Git abstractions - staged files, diff, repo root, push, commit, checkout, merge, reset, force-push, delete-remote-branch, divergence
-│       ├── file-utils.js             # File operations - repo-relative paths
-│       ├── logger.js                 # Logging system - centralized output, debug mode
-│       ├── preset-loader.js          # Preset system - load tech-stack configurations
-│       ├── pr-metadata-engine.js     # PR metadata generation - branch context, diff reduction, metadata (v2.14.0)
-│       ├── github-api.js             # Octokit integration - PR creation, PR analysis, token validation, Teams API
-│       ├── github-client.js          # GitHub helpers - repo parsing, config-based reviewers (fallback)
-│       ├── reviewer-selector.js      # Team-based reviewer selection - resolve team members, exclude author (v2.32.0)
-│       ├── authorization.js           # Role-based authorization - PROTECTED_COMMANDS, authorizeCommand(), fail-closed (v2.23.0)
-│       ├── remote-config.js          # Remote config fetcher - cached JSON from git-hooks-config repo (v2.31.0)
-│       ├── label-resolver.js         # Label resolution - 5-rule engine with remote + local fallback (v2.31.0)
-│       ├── token-store.js            # Token persistence - centralized settings.local.json read/write
-│       ├── linear-connector.js       # Linear API - ticket context fetching with retry
-│       ├── coupling-detector.js      # Coupling algorithm - Union-Find transitive grouping (v2.23.0)
-│       ├── pr-statistics.js          # PR statistics - write-only JSONL analytics
-│       ├── task-id.js                # Task ID extraction - Jira, GitHub, Linear patterns
-│       ├── interactive-ui.js         # CLI UI components - previews, prompts, spinners
-│       ├── judge.js                  # Auto-fix judge - LLM verdict + search/replace fixes (v2.20.0)
-│       ├── resolution-prompt.js      # Issue resolution - AI-friendly fix prompts
-│       ├── installation-diagnostics.js # Installation diagnostics - error context
-│       ├── claude-diagnostics.js     # Claude errors - rate limit, auth, formatting
-│       ├── which-command.js          # Executable resolution - cross-platform paths
-│       ├── sanitize.js               # Input sanitization - shell safety
-│       ├── telemetry.js              # Local telemetry - track JSON parsing, retries
-│       ├── version-manager.js        # Version detection - parse, increment, validate, per-file targets (v2.12.0)
-│       ├── git-tag-manager.js        # Git tag operations - create, list, compare, push, isSemverTag (v2.12.0)
-│       └── changelog-generator.js    # CHANGELOG generation - Claude-powered analysis (v2.12.0)
-├── templates/                        # Static assets - copied during install
-│   ├── pre-commit                    # Bash wrapper - invokes lib/hooks/pre-commit.js
-│   ├── prepare-commit-msg            # Bash wrapper - invokes lib/hooks/prepare-commit-msg.js
-│   ├── check-version.sh              # Version check - auto-update prompt
-│   ├── CLAUDE_PRE_COMMIT.md          # Analysis criteria - evaluation guidelines
-│   ├── CLAUDE_ANALYSIS_PROMPT.md     # Analysis prompt - code review template
-│   ├── CLAUDE_RESOLUTION_PROMPT.md   # Resolution prompt - structured JSON output for judge + manual use
-│   ├── ANALYZE_DIFF.md               # PR analysis - diff review template
-│   ├── ANALYZE_PR.md                 # PR analysis - GitHub PR review template with category injection
-│   ├── GENERATE_CHANGELOG.md         # CHANGELOG generation - commit analysis template (v2.12.0)
-│   ├── DIFF_ANALYSIS_ORCHESTRATION_PROMPT.md  # Orchestration prompt - Opus batch grouping (v2.20.0)
-│   ├── HELP_QUERY.md                 # AI help - question answering with NEED_MORE_CONTEXT protocol (v2.18.0)
-│   ├── HELP_REPORT_ISSUE.md          # Report issue - question generation from templates (v2.18.0)
-│   ├── HELP_COMPOSE_ISSUE.md         # Report issue - issue body composition from answers (v2.18.0)
-│   ├── config.example.json           # Config example - minimal setup
-│   ├── config.advanced.example.json  # Config advanced - all options documented
-│   ├── settings.local.example.json   # Local settings - token storage template
-│   └── CUSTOMIZATION_GUIDE.md        # Customization - preset creation guide
-└── test/                             # Tests - Jest with ES6 modules
-    └── unit/
-        └── *.test.js
-```
-
-### Execution Architecture
-
-**1. Git Hooks (bash wrappers → Node.js)**
-
-```
-.git/hooks/pre-commit (bash)
-  ↓
-node lib/hooks/pre-commit.js
-  ↓ (reads config + preset)
-lib/config.js → merges: defaults < user config < preset config
-  ↓ (gets staged files)
-lib/utils/git-operations.js → getStagedFiles()
-  ↓ (filters by preset extensions + size)
-lib/utils/file-operations.js → filterFiles()
-  ↓ (builds file data + runs analysis)
-lib/utils/analysis-engine.js → buildFilesData(), runAnalysis()
-  ↓ (2-tier routing: 1-2 files→sequential, 3+→Opus orchestration)
-lib/utils/diff-analysis-orchestrator.js → orchestrateBatches() [if N ≥ 3]
-lib/utils/claude-client.js → analyzeCode(prompt, { model }) per batch [parallel]
-  ↓ (displays results)
-lib/utils/analysis-engine.js → displayResults()
-  ↓ (if blocking issues found)
-lib/utils/resolution-prompt.js → generates claude_resolution_prompt.md
-  ↓
-exit 1 (blocks commit) or exit 0 (allows commit)
-```
-
-**2. Configuration System (priorities)**
-
-```
-defaults (lib/config.js)
-  ↓ overridden by
-user config (.claude/config.json)
-  ↓ overridden by
-preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
-```
-
-**Rationale**: User configures general preferences, preset provides tech-stack-specific overrides.
-
-**Team-wide remote config** ([`mscope-S-L/git-hooks-config`](https://github.com/mscope-S-L/git-hooks-config)):
-
-- `labels.json` — PR label rules (fetched by `remote-config.js`, consumed by `label-resolver.js`)
-- `formatters.json` — preset-to-tools mapping for linting/formatting (fetched by `remote-config.js`, consumed by `linter-runner.js`)
-- `permissions.json` — role-based authorization (fetched directly by `authorization.js`, fail-closed)
-- Changes take effect immediately across all governed repos — no tool update needed
-
-**Config format (v2.8.0):**
-
-```json
-{
-    "version": "2.8.0",
-    "preset": "backend",
-    "overrides": {
-        "github": {
-            "pr": {
-                "defaultBase": "develop",
-                "reviewers": ["user"],
-                "autoPush": true, // Auto-push unpublished branches (v2.11.0)
-                "pushConfirm": true, // Prompt before push (v2.11.0)
-                "showCommits": true, // Show commit preview (v2.11.0)
-                "verifyRemote": true // Verify remote exists (v2.11.0)
-            }
-        }
-    }
-}
-```
-
-**Hardcoded defaults (v2.8.0+):**
-
-| Parameter              | Value   | Notes                                               |
-| ---------------------- | ------- | --------------------------------------------------- |
-| Max file size          | 1MB     | Files larger are skipped                            |
-| Max files per commit   | 30      | Excess files trigger warning                        |
-| Orchestrator threshold | 3 files | Commits with ≥3 files use Opus orchestration        |
-| Orchestrator model     | opus    | Internal constant — not user-configurable           |
-| Orchestrator timeout   | 60s     | Lightweight call (file overview only)               |
-| Analysis timeout       | 360s    | Per-batch timeout                                   |
-| Commit msg timeout     | 300s    | Message generation timeout                          |
-| PR metadata timeout    | 180s    | Engine default (reads config)                       |
-| Judge model            | sonnet  | Default, configurable via `config.judge.model`      |
-| Judge timeout          | 360s    | Per-judge call timeout                              |
-| PR analysis model      | sonnet  | Default, configurable via `config.prAnalysis.model` |
-| PR analysis timeout    | 300s    | Per-analysis Claude call                            |
-| Linting enabled        | true    | Runs linters before Claude analysis                 |
-| Linting auto-fix       | true    | Auto-fix and re-stage files                         |
-| Linting fail on error  | true    | Block commit on linting errors                      |
-| Linting fail on warn   | false   | Do not block on warnings                            |
-| Linting timeout        | 30s     | Per-linter timeout (tool-specific overrides if higher) |
-| Spotless timeout       | 120s    | Per-invocation; overrides config default             |
-
-**Judge behavior (v2.20.0):**
-
-- Enabled by default (`config.judge?.enabled !== false`)
-- Runs on **all issues** (any severity), not just blockers
-- **Any unresolved issue blocks the commit** — no issue passes without judge approval
-- Judge failure (timeout, JSON parse error, module load) → user warned → commit blocked
-- No retries — failed fixes stay as unresolved issues
-- When disabled (`config.judge.enabled: false`), falls back to original quality gate (blocks on CRITICAL/BLOCKER only)
-- Resolution prompt file is only generated if issues remain after the judge
-
-**3. Presets System**
-
-| Preset      | Extensions                                                                 | Stack                    | Key Verifications                                   |
-| ----------- | -------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------- |
-| `backend`   | `.java`, `.xml`, `.yml`, `.yaml`                                           | Spring Boot + SQL Server | REST API, JPA, OWASP Top 10, SQL injection          |
-| `frontend`  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | React + Material-UI      | Hooks, XSS, a11y, performance                       |
-| `fullstack` | backend + frontend                                                         | Spring Boot + React      | **API contract consistency** (priority)             |
-| `database`  | `.sql`                                                                     | SQL Server               | SQL injection, UPDATE/DELETE without WHERE, indexes |
-| `ai`        | `.js`, `.json`, `.md`, `.sh`                                               | Node.js + Claude API     | Prompts, API key security, cross-platform           |
-| `default`   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Multiple                 | Quality and security fundamentals                   |
-
-**4. Analysis Routing (v2.20.0)**
-
-Three-tier strategy based on file count:
-
-| Files  | Strategy                                                                                              |
-| ------ | ----------------------------------------------------------------------------------------------------- |
-| 1–2    | Sequential — single Claude call                                                                       |
-| **3+** | **Intelligent orchestration** — Opus orchestrator, semantic grouping, per-batch model, shared context |
-
-**Orchestration flow (3+ files):**
-
-```
-staged files (N ≥ 3)
-  ↓
-[ORCHESTRATOR — Opus, 60s timeout]
-  Input: file overview table + detected cross-file deps (JS/TS/Java/Python regex)
-  Output: { batches: [{ filePaths, rationale, model }] }
-  ↓
-For each batch:
-  → buildAnalysisPrompt(batchFiles + commonContext + batchRationale)
-  → analyzeCode(prompt, { model: batch.model })     ← per-batch model
-  [all batches run in parallel via Promise.all]
-  ↓
-consolidateResults()
-```
-
-- **Orchestration model**: `opus` — hardcoded internal constant, not user-configurable
-- **Threshold**: `ORCHESTRATOR_THRESHOLD = 3` — internal constant in `analysis-engine.js`
-- **Fallback**: any orchestration failure → one-file-per-batch with haiku
-- **Common context**: each batch prompt prefixed with commit overview, dep graph, and batch rationale
-
-### Key Module Exports
-
-**Command Modules (`lib/commands/`):**
-
-| Module                  | Purpose                     | Key Exports                                                                                        |
-| ----------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
-| `helpers.js`            | Shared CLI utilities        | `colors`, `error()`, `success()`, `info()`, `checkGitRepo()`, `getGitHooksPath()`, `Entertainment` |
-| `install.js`            | Installation logic          | `runInstall()`, `extractLegacySettings()`                                                          |
-| `hooks.js`              | Hook management             | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()`                                     |
-| `analyze.js`            | Interactive code analysis   | `runAnalyze()`                                                                                     |
-| `analyze-diff.js`       | Diff analysis               | `runAnalyzeDiff()`                                                                                 |
-| `analyze-pr.js`         | PR analysis from URL        | `runAnalyzePr()`, `normalizeCategory()`                                                            |
-| `check-coupling.js`     | Coupling detection          | `runCheckCoupling()`                                                                               |
-| `shadow.js`             | Shadow branch management    | `runShadow()` — routes to analyze/reset/sync subcommands (v2.24.0)                                 |
-| `create-release.js`     | Release candidate creation  | `runCreateRelease()` — RC branch from develop, version bump, push, shadow deploy (v2.27.0)         |
-| `revert-feature.js`     | Feature revert in RC        | `runRevertFeature()` — find by task-id, coupling check, revert, push, shadow sync (v2.28.0)        |
-| `close-release.js`      | Release candidate closure   | `runCloseRelease()` — soft-reset, single commit, force-push, PR to main (v2.29.0)                  |
-| `create-pr.js`          | PR creation                 | `runCreatePr()`, `detectMergeStrategy()` (private)                                                 |
-| `bump-version.js`       | Version management          | `runBumpVersion()`                                                                                 |
-| `generate-changelog.js` | CHANGELOG generation        | `runGenerateChangelog()`                                                                           |
-| `setup-github.js`       | Token setup (GitHub)        | `runSetupGitHub()`                                                                                 |
-| `setup-linear.js`       | Token setup (Linear)        | `runSetupLinear()`                                                                                 |
-| `presets.js`            | Preset management           | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()`                                         |
-| `update.js`             | Self-update                 | `runUpdate()`                                                                                      |
-| `migrate-config.js`     | Config migration            | `runMigrateConfig()`                                                                               |
-| `debug.js`              | Debug toggle                | `runSetDebug()`                                                                                    |
-| `telemetry-cmd.js`      | Telemetry commands          | `runShowTelemetry()`, `runClearTelemetry()`                                                        |
-| `diff-batch-info.js`    | Batch info display          | `runDiffBatchInfo()`                                                                               |
-| `lint.js`               | Lint command                | `runLint()`, `resolvePaths()`                                                                      |
-| `help.js`               | Help, AI help, report-issue | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()`                                            |
-
-**Utility Modules (`lib/utils/`):**
-
-| Module                          | Purpose                         | Key Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lib/cli-metadata.js`           | Command registry                | `commands`, `buildCommandMap()`, `generateCompletionData()`, `PRESET_NAMES`, `HOOK_NAMES`, `BUMP_TYPES`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `lib/config.js`                 | Config system                   | `getConfig()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `tool-runner.js`                | Generic tool executor           | `isToolAvailable()`, `filterFilesByTool()`, `runTool()`, `runToolFix()`, `runToolWithAutoFix()`, `displayToolResult()` (v2.34.0)                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `linter-runner.js`              | Linter orchestration            | `runLinters()`, `displayLintResults()`, `checkLinterAvailability()`, `getLinterToolsForPreset()`, `LINTER_TOOLS`, `PRESET_LINTERS`, `parsePrettierOutput()`, `parseEslintOutput()`, `parseSpotlessOutput()`, `parseSqlfluffOutput()`, `filesToSpotlessRegex()` (v2.34.0)                                                                                                                                                                                                                                                                                   |
-| `analysis-engine.js`            | Shared analysis logic           | `buildFileData()`, `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `hasBlockingIssues()`, `hasAnyIssues()`, `displayResults()`, `displayIssueSummary()` (v2.13.0+)                                                                                                                                                                                                                                                                                                                                                                            |
-| `diff-analysis-orchestrator.js` | Intelligent batch orchestration | `orchestrateBatches()`, `buildFileOverview()`, `detectDependencies()` (v2.20.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `claude-client.js`              | Claude CLI wrapper              | `analyzeCode()`, `executeClaudeWithRetry()`, `extractJSON()` — spawn, retry, model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `prompt-builder.js`             | Prompt construction             | `buildAnalysisPrompt()`, `loadPrompt()` — accepts `commonContext`, `batchRationale`                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `git-operations.js`             | Git abstractions                | `getStagedFiles()`, `getUnstagedFiles()`, `getAllTrackedFiles()`, `getDiff()`, `getRepoRoot()`, `getBranchPushStatus()`, `pushBranch()`, `createCommit()`, `fetchRemote()`, `branchExists()`, `getRemoteBranches()`, `resolveBaseBranch()`, `getChangedFilesBetweenRefs()`, `getDiffBetweenRefs()`, `getCommitsBetweenRefs()`, `checkoutBranch()`, `mergeBranch()`, `resetBranch()`, `forcePush()`, `deleteRemoteBranch()`, `getDivergence()`, `readFileFromRef()`, `getLatestTag()`, `isWorkingDirectoryClean()`, `getActiveBranch()`, `getCommitFiles()` |
-| `file-utils.js`                 | File operations                 | `ensureDir()`, `ensureOutputDir()`, `writeOutputFile()`, `walkDirectoryTree()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `pr-metadata-engine.js`         | PR metadata generation          | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` (v2.14.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `git-tag-manager.js`            | Git tag operations              | `createTag()`, `pushTags()`, `getLocalTags()`, `getRemoteTags()`, `compareLocalAndRemoteTags()`, `tagExists()` (v2.12.0)                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `version-manager.js`            | Version management              | `discoverVersionFiles()`, `getDiscoveryResult()`, `readVersionFromFile()`, `writeVersionToFile()`, `updateVersionFiles()`, `modifySuffix()`, `incrementVersion()`, `parseVersion()`, `validateVersionFormat()`, `compareVersions()`, `validateVersionAlignment()` (v2.15.5)                                                                                                                                                                                                                                                                                |
-| `changelog-generator.js`        | CHANGELOG generation            | `generateChangelogEntry()`, `updateChangelogFile()`, `getLastFinalVersionTag()`, `getCommitsSinceTag()`, `discoverChangelogFiles()`, `selectChangelogFile()` (v2.12.0)                                                                                                                                                                                                                                                                                                                                                                                     |
-| `coupling-detector.js`          | Coupling algorithm              | `buildFileIndex()`, `getSharedFiles()`, `detectCouplingGroups()` — Union-Find transitive grouping (v2.23.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `github-api.js`                 | Octokit integration             | `createPullRequest()`, `fetchPullRequest()`, `fetchPullRequestFiles()`, `createPullRequestReview()`, `parseGitHubPRUrl()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()`, `listOpenPullRequests()`, `listRepoTeams()`, `listTeamMembers()`, `getAuthenticatedUser()`, `checkOrgMembership()`, `getCollaboratorPermission()`                                                                                                                                                                      |
-| `github-client.js`              | GitHub helpers                  | `getReviewersForFiles()`, `parseGitHubRepo()` — config-based reviewer fallback                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `reviewer-selector.js`          | Team-based reviewer selection   | `selectReviewers()` — resolve team members via GitHub Teams API, exclude PR author, config fallback (v2.32.0)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `authorization.js`              | Role-based authorization        | `authorizeCommand()`, `requiresAuthorization()`, `getRequiredRole()`, `AuthorizationError`, `PROTECTED_COMMANDS` — fail-closed guard for workflow commands (v2.23.0)                                                                                                                                                                                                                                                                                                                                                                                       |
-| `remote-config.js`              | Remote config fetcher           | `fetchRemoteConfig(fileName)`, `CONFIG_REPO_OWNER`, `CONFIG_REPO_NAME`, `_clearCache()` — cached JSON from `git-hooks-config` repo, graceful degradation (v2.31.0)                                                                                                                                                                                                                                                                                                                                                                                         |
-| `label-resolver.js`             | Label resolution                | `resolveLabels(context)` — 5-rule engine: preset, size, quality, strategy, defaults; remote config priority with local fallback (v2.31.0)                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `token-store.js`                | Token persistence               | `loadToken()`, `saveToken()`, `hasToken()`, `loadLocalSettings()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `linear-connector.js`           | Linear integration              | `loadLinearToken()`, `testConnection()`, `fetchTicket()`, `extractLinearTicketFromTitle()`, `parseLinearIdentifier()`, `LinearConnectorError`                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `pr-statistics.js`              | PR statistics                   | `recordPRAnalysis()` — write-only JSONL at `.claude/statistics/pr/stats.jsonl`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `preset-loader.js`              | Preset system                   | `loadPreset()`, `listPresets()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `task-id.js`                    | Task ID extraction              | `getOrPromptTaskId()`, `formatWithTaskId()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `logger.js`                     | Logging system                  | `info()`, `warning()`, `error()`, `debug()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `judge.js`                      | Auto-fix judge                  | `judgeAndFix()`, `applyFix()` — LLM verdict + search/replace fixes (v2.20.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `resolution-prompt.js`          | Issue resolution                | `generateResolutionPrompt()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `interactive-ui.js`             | CLI UI components               | `showPRPreview()`, `promptConfirmation()`, `promptMenu()`, `promptToggleList()`, `promptEditField()`, `promptUserConfirmation()`                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `telemetry.js`                  | Local telemetry                 | `recordEvent()`, `displayStatistics()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-
-### Design Patterns
-
-1. **Command Registry**: `lib/cli-metadata.js` - single source of truth for CLI commands, flags, and descriptions. When adding CLI commands, add an entry to `lib/cli-metadata.js` — routing, completions, and help derive from it.
-2. **Command Pattern**: `lib/commands/*.js` - each CLI command is a self-contained module
-3. **Factory Pattern**: `preset-loader.js` loads configurations dynamically per tech-stack
-4. **Template Method**: `prompt-builder.js` builds prompts from markdown templates
-5. **Strategy Pattern**: `analysis-engine.js` selects between sequential (1–2 files) or orchestrated (3+ files) analysis based on file count threshold
-6. **Orchestrator Pattern**: `diff-analysis-orchestrator.js` — Opus decides semantic grouping and model assignment; workers (analyzeCode per batch) execute in parallel
-7. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
-8. **Singleton Pattern**: `config.js` loads configuration once per execution
-9. **Guard Pattern**: `authorization.js` — fail-closed gate in `bin/claude-hooks` before command dispatch; static `PROTECTED_COMMANDS` set avoids API calls for unprotected commands; permissions sourced from `mscope-S-L/git-hooks-config/permissions.json`
-10. **Remote Config Pattern**: `remote-config.js` — fetches JSON from `mscope-S-L/git-hooks-config`, caches per-process (including nulls), graceful degradation (warn + return null); `label-resolver.js` and `linter-runner.js` — callers fetch remote config and decide fallback (`labels.json` for PR labels, `formatters.json` for preset-to-tools mapping)
-11. **Pipeline Pattern**: `tool-runner.js` + `linter-runner.js` — generic tool execution infrastructure; formatters (Prettier) and linters (ESLint, Spotless, sqlfluff) share the same resolve → spawn → parse → fix → re-stage pipeline. Tool definitions are data objects, not classes. Preset-to-tools mapping fetched from `mscope-S-L/git-hooks-config/formatters.json` (remote config priority, local fallback).
-
-### Key Data Flows
-
-**Flow 0: Pre-commit linting (v2.34.0)**
-
-```
-git commit
-  → hook reads staged files
-  → filters by preset extensions + size
-  ↓
-  → LINTING STEP (fast, deterministic)
-    → getLinterToolsForPreset(presetName):
-        1. fetchRemoteConfig('formatters.json') → remote presetTools mapping
-        2. fallback to local PRESET_LINTERS if remote unavailable
-    → for each tool (formatters first, then linters):
-        isToolAvailable() → not found? warn + install hint → skip
-        filterFilesByTool() → matching files
-        → timeout = max(config.linting.timeout, toolDef.timeout)
-        → perFile tools (Spotless): resolve command path
-            .cmd/.bat → per-file mode (cmd.exe pipe safety)
-            otherwise → batch mode (single JVM startup)
-        runToolWithAutoFix() → check → auto-fix → re-stage → re-check
-    → unfixable issues forwarded to judge
-  ↓
-  → continues to Claude analysis
-```
-
-**Flow 1: Pre-commit with blocking**
-
-```
-git commit
-  → hook reads staged files
-  → filters by preset extensions
-  → [linting step — see Flow 0]
-  → builds prompt with diff
-  → Claude analyzes → detects issues
-  → judge evaluates ALL issues (any severity):
-    → TRUE_ISSUE: applies search/replace fix + git add
-    → FALSE_POSITIVE: dismissed
-    → if ALL resolved: exit 0 → COMMIT PROCEEDS
-    → if ANY unresolved: generates resolution prompt → exit 1 → COMMIT BLOCKED
-    → if judge fails (timeout, parse error): user warned → exit 1 → COMMIT BLOCKED
-  → judge disabled (config.judge.enabled: false):
-    → falls back to original quality gate (blocks on CRITICAL/BLOCKER only)
-```
-
-**Flow 1.5: Interactive analysis command (v2.13.0)**
-
-```
-claude-hooks analyze
-  → runs outside git hook context (stdin works)
-  → getStagedFiles() → buildFilesData() → runAnalysis()
-  → displayIssueSummary() → shows all severity levels (or "No issues found")
-  → promptUserConfirmation() → interactive menu:
-    → [y] Continue - executes createCommit('auto', { noVerify: true })
-    → [n] Abort - generates resolution prompt
-    → [v] View - shows detailed issues → returns to menu
-  → on continue: git commit -m "auto" --no-verify
-    → prepare-commit-msg hook generates message via Claude
-    → commit created with auto-generated message
-```
-
-**Flow 2: Commit with automatic message**
-
-```
-git commit -m "auto"
-  → hook extracts task-id from branch (feature/IX-123-add-auth)
-  → Claude generates message → "[IX-123] feat: add user authentication"
-  → writes to .git/COMMIT_EDITMSG
-  → commit proceeds with generated message
-```
-
-**Flow 3: Analyze diff (v2.14.0)**
-
-```
-claude-hooks analyze-diff develop
-  → lib/commands/analyze-diff.js (thin wrapper)
-  → analyzeBranchForPR() (pr-metadata-engine.js)
-    → fetchRemote() → resolveBaseBranch() (suggests similar branches if not found)
-    → getChangedFilesBetweenRefs() → getCommitsBetweenRefs()
-    → buildDiffPayload() → tiered reduction (context → proportional → stat-only)
-    → executeClaudeWithRetry() → parses PRMetadata
-  → formats metadata to console
-  → saves to .claude/out/pr-analysis.json
-```
-
-**Flow 3.5: Analyze PR from GitHub URL**
-
-```
-claude-hooks analyze-pr https://github.com/owner/repo/pull/123
-  → parseGitHubPRUrl() → { owner, repo, number }
-  → fetchPullRequest() + fetchPullRequestFiles() via Octokit
-  → extractLinearTicketFromTitle() → fetchTicket() (optional enrichment)
-  → resolvePreset(): CLI flag → PR labels → ticket labels → auto-detect from extensions → 'default'
-  → loadPrompt('ANALYZE_PR.md') with preset guidelines + category injection
-  → executeClaudeWithRetry() → extractJSON() → normalizeCategory() with fuzzy aliases
-  → interactive comment workflow: post all / select / skip
-  → createPullRequestReview() with inline comments + review body
-  → recordPRAnalysis() → .claude/statistics/pr/stats.jsonl
-```
-
-**Flow 4: PR creation (with auto-push v2.11.0, engine v2.14.0, merge strategy v2.25.0, label resolver v2.31.0, team reviewers v2.32.0)**
-
-```
-claude-hooks create-pr develop
-  → checks branch push status (unpublished/unpushed commits)
-  → shows commit preview → prompts for confirmation
-  → pushes branch to remote (if needed)
-  → selectReviewers({ org, teamSlug, prAuthor, configReviewers }):
-      1. listTeamMembers(org, teamSlug) → resolve team (default: 'automation')
-      2. filter out prAuthor
-      3. if team empty or API fails → fall back to config.github.pr.reviewers
-  → detectMergeStrategy(sourceBranch, targetBranch):
-      feature/* → squash | release-fix/* → squash
-      release-candidate/* → merge-commit | hotfix/* → merge-commit
-      any → main → merge-commit | unknown → user prompted to select
-  → resolveLabels({ preset, fileCount, mergeStrategy, analysisResult, localLabelRules }):
-      1. preset labels (remote presetLabels or local fallback)
-      2. size labels: size:S (<10) | size:M (10-50) | size:L (50-100) | size:XL (>100)
-      3. quality labels: breaking-change, security, performance (from analysisResult)
-      4. strategy label: merge-strategy:squash or merge-strategy:merge-commit
-      5. default labels (from remote config only, e.g. needs-review)
-  → prepends body reminder for merge-commit
-  → analyzeBranchForPR() (pr-metadata-engine.js) → generates metadata
-  → interactive preview + strategy info line → user confirms
-  → Octokit creates PR on GitHub
-```
-
-**Flow 5: Version bump with per-file editing (v2.16.0)**
-
-```
-claude-hooks bump-version patch --interactive
-  → validatePrerequisites() → clean working directory, valid branch, remote
-  → discoverVersionFiles() → recursive scan (max 3 levels)
-  → displayDiscoveryTable() → shows all discovered files with versions
-  → promptFileSelection() → interactive menu:
-    → [a] Update all files - all files get same newVersion
-    → [s] Select files - toggle list to pick subset
-    → [e] Edit per file - promptEditField() per file:
-      → user enters custom version per file (Enter keeps calculated version)
-      → validateVersionFormat() → rejects invalid entries
-      → stores file.targetVersion on each descriptor
-    → [c] Cancel
-  → incrementVersion() / modifySuffix() → calculates newVersion (used for tag + commit)
-  → updateVersionFiles() → uses file.targetVersion || newVersion per file
-  → createTag(newVersion) → tag reflects primary release version
-  → commit message uses newVersion
-```
-
-**Per-file version design**: `VersionFileDescriptor` gains an optional `targetVersion` property at runtime, set only by option 'e'. When present, `updateVersionFiles()` writes `targetVersion` instead of the global `newVersion`. The tag and commit message always use the calculated `newVersion`.
-
-**Flow 6: Release candidate creation (v2.27.0)**
-
-```
-claude-hooks create-release minor
-  → parseArguments() → bumpType, noShadow, dryRun, skipPush, updateChangelog
-  → validatePreconditions():
-      checkGitRepo()
-      isWorkingDirectoryClean()             → abort if dirty
-      getCurrentBranch() === 'develop'      → abort if not on develop
-      fetchRemote()                         → warn on failure, continue
-      getDivergence('develop','origin/develop') → behind>0 → abort + git pull advice
-      getDivergence('origin/develop','origin/main') → behind>0 → abort + back-merge advice
-      getRemoteBranches().filter('release-candidate/*') → any found → abort + close-release advice
-      verifyRemoteExists()
-  → discoverVersionFiles()
-      mismatch → abort with table + fix steps (non-interactive, cannot auto-resolve)
-  → incrementVersion(currentVersion, bumpType)  [no suffix in branch name]
-  → rcBranch = 'release-candidate/V{nextVersion}'
-  → [--dry-run] → preview table → return
-  → promptConfirmation()
-  → checkoutBranch(rcBranch, { create: true, startPoint: 'develop' })
-  → updateVersionFiles()
-  → [--update-changelog] → generateChangelogEntry() + updateChangelogFile()
-  → stageFiles() + createCommit('chore(version): bump to {nextVersion}', { noVerify: true })
-  → tagExists()? → warn + skip : createTag()
-  → [unless --skip-push] pushBranch(rcBranch, { setUpstream: true })
-  → [unless --no-shadow and not --skip-push] runShadow(['sync', rcBranch])
-      shadow error → warn, don't abort
-  → checkoutBranch(rcBranch)  [safety: ensure we land on RC after shadow sync]
-  → display summary (branch, version, tag, push status, shadow status)
-```
-
-**create-release design decisions:**
-
-- Mismatch aborts non-interactively (automation context — ambiguity must be fixed by human)
-- Tag creation mirrors `bump-version`: created on RC branch; if tag already exists → warn + skip (no interactive prompt)
-- Shadow sync delegates to `runShadow(['sync', rcBranch])` (public API, reuses conflict-resolution logic from #93)
-- `--skip-push` implies no shadow (cannot sync unpushed branch)
-- Branch naming: `release-candidate/V{semver}` — capital V per team convention, no suffix in branch name
-
-**Flow 7: Feature revert in release-candidate (v2.28.0)**
-
-```
-claude-hooks revert-feature AUT-3179
-  → parseArgs() → taskId, updateShadow, dryRun
-  → getCurrentBranch() — must start with 'release-candidate/'
-  → isWorkingDirectoryClean()           → abort if dirty
-  → git log --grep="AUT-3179" --fixed-strings -i origin/main..HEAD
-      0 matches → abort
-      1 match  → show commit details (hash, message, author, date, files)
-      2+ matches → promptMenu() → user selects one
-  → getCommitFiles(targetHash)          → target file set
-  → _checkCoupling(): for each other RC commit (skip target, skip Revert commits):
-      getCommitFiles(hash) → intersect with targetFiles → collect { taskId, sharedFiles }
-  → [--dry-run] → preview table → return
-  → _displayCommitDetails() + coupling warnings (informational, before single confirmation)
-  → promptConfirmation('Proceed with revert?', false)
-  → git revert --no-edit <hash>         → stdio: inherit (shows git output)
-  → git rev-parse HEAD                  → revertHash
-  → pushBranch(rcBranch)
-  → _appendRevertLog(): append { taskId, originalHash, revertHash, rcBranch, timestamp }
-       to .claude/revert-log.json (array, consumed by back-merge #96)
-  → [--update-shadow] runShadow(['sync', rcBranch]) → warn on failure, don't abort
-  → display summary + revert-the-revert reminder:
-       git revert <revertHash>    # Restores AUT-3179 for next sprint
-```
-
-**revert-feature design decisions:**
-
-- Coupling check is informational only — warnings shown before single confirmation (no second prompt)
-- `Revert "..."` commits are skipped in coupling scan (they intentionally share files)
-- `revert-log.json` schema: `[{ taskId, originalHash, revertHash, rcBranch, timestamp }]` — array to support multiple reverts; consumed by back-merge (#96)
-- `git revert` uses `stdio: 'inherit'` so the user sees git output (including conflict messages)
-- Push failure: revert commit is kept locally; user shown manual `git push` command
-- Shadow sync error: warns but does not abort (non-fatal, same pattern as `create-release`)
-
-**Flow 8: Release candidate closure (v2.29.0)**
-
-```
-claude-hooks close-release "cashflow + auth"
-  → _parseArgs() → description, autoDescribe, dryRun, noPr
-  → detect RC branch: current branch or getActiveBranch('release-candidate') → offer checkout
-  → _extractVersion(rcBranch) → semver string
-  → isWorkingDirectoryClean()     → abort if dirty
-  → fetchRemote()                 → warn on failure
-  → getDivergence(rc, origin/rc)  → behind>0 → abort + git pull advice
-  → _collectFeatureList(): getCommitsBetweenRefs('origin/main', 'HEAD', { format: '%s' })
-  → _resolveDescription():
-      CLI arg → use directly
-      --auto-describe → executeClaudeWithRetry(haiku, 60s) → 1-line phrase
-      default → show list + promptEditField() → TL accepts or overrides
-  → [--dry-run] → preview table → return
-  → promptConfirmation()
-  → resetBranch('origin/main', { mode: 'soft' }) — all RC commits staged
-  → execSync('git commit --no-verify -F -', { input: fullMessage }) — subject + body
-  → forcePush(rcBranch, { lease: true })
-  → [unless --no-pr] validateToken() + createPullRequest(head→main, label: merge-strategy:merge-commit)
-  → display summary with PR URL + merge-commit reminder
-```
-
-**close-release design decisions:**
-
-- `git commit --no-verify -F -` (stdin) is used instead of `createCommit()` to support multi-line body; `execSync` passes the full message via `input` option (no shell injection risk — fixed string)
-- `process.exit()` calls are placed _outside_ try/catch blocks so that mock-based tests can observe them; the catch only handles git errors
-- Description priority: CLI arg > `--auto-describe` (Claude haiku, 60s timeout) > `promptEditField` (shows list, TL edits)
-- Auto-describe fallback: if Claude fails or feature list is empty, falls back to interactive prompt without aborting
-- `close-release` was already in `PROTECTED_COMMANDS` — authorization.js unchanged
-- Force-push failure: exits 1 and shows manual push command (no retry — destructive op)
-- PR creation failure: warns + shows `gh pr create` alternative (non-fatal; commit and push already done)
-- `_extractVersion`, `_collectFeatureList`, `_resolveDescription` are exported for unit testing
-
-## Code Conventions
-
-### General Style
-
-- **Format**: Prettier (config in `.prettierrc.json`)
-- **Linting**: ESLint 8.57.0 (config in `.eslintrc.json`)
-- **Indentation**: 4 spaces
-- **Quotes**: Single quotes (strings), double quotes (HTML/imports)
-- **Semicolons**: Required
-
-### Naming
-
-- **Files**: `kebab-case.js` (e.g., `claude-client.js`, `git-operations.js`)
-- **Functions**: `camelCase()` (e.g., `getStagedFiles()`, `buildAnalysisPrompt()`)
-- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_FILE_SIZE`, `ALLOWED_EXTENSIONS`)
-- **Classes**: Not applicable (no classes, only exported functions)
-- **Private variables**: `_` prefix (e.g., `_internalHelper()`)
-
-### Exports
-
-**Preferred pattern - Named exports:**
-
-```javascript
-// lib/utils/example.js
-export function doSomething() { ... }
-export function doOtherThing() { ... }
-
-// consumer
-import { doSomething, doOtherThing } from './utils/example.js';
-```
-
-**Avoid default exports** (except in `bin/claude-hooks` per CLI convention).
-
-### Error Handling
-
-**Standard pattern:**
-
-```javascript
-import { error } from './utils/logger.js';
-
-try {
-    const result = dangerousOperation();
-    return result;
-} catch (err) {
-    error(`Failed to perform operation: ${err.message}`);
-    process.exit(1); // In hooks and CLI commands
-    // or throw err; // In library functions
-}
-```
-
-**Specific errors:**
-
-- Git operations → `execSync()` with try-catch, log and exit
-- Claude CLI → retry logic in `claude-client.js`, configurable timeout
-- GitHub API → catch `@octokit/request-error`, user-friendly formatting
-
-### Logging
-
-```javascript
-import { info, warning, error, debug } from './utils/logger.js';
-
-info('✅ Operation completed'); // User-facing messages
-warning('⚠️ Non-blocking issue detected'); // Warnings
-error('❌ Critical failure'); // Errors
-debug('Detailed diagnostic info'); // Only shown when debug=true
-```
-
-**Debug mode**: Activate with `claude-hooks --debug true` or in `.claude/config.json`.
-
-### Async/Await
-
-**Prefer async/await over callbacks:**
-
-```javascript
-// ✅ GOOD
-async function analyzeCode(prompt) {
-    const result = await spawnClaude(prompt);
-    return result;
-}
-
-// ❌ BAD
-function analyzeCode(prompt, callback) {
-    spawnClaude(prompt, callback);
-}
-```
-
-### Reusable Modules
-
-All modules in `lib/utils/` must:
-
-1. Export pure functions (no global side effects)
-2. Include inline JSDoc documentation
-3. Accept configuration via parameters (no globals)
-4. Return structured results (objects or arrays)
-5. Log with `logger.js` (no direct `console.log`)
-
-## Workflow
-
-### Branching Strategy
-
-This repository follows **simplified GitHub Flow**:
-
-- **Main branch**: `main` (protected)
-- **Feature branches**: `feature/issue-description` or `feature/TASK-ID-description`
-- **Fix branches**: `fix/issue-description`
-- **Hotfix branches**: `hotfix/urgent-description`
-
-**Rules:**
-
-1. All changes require PR to `main`
-2. No direct commits to `main`
-3. PRs require review (auto-merge NOT allowed)
-
-### Development Process
-
-**1. Initial setup (first time)**
-
-```bash
-git clone https://github.com/mscope-S-L/git-hooks.git
-cd git-hooks
-npm install
-npm link  # Install globally as symlink for development
-```
-
-**2. Create feature branch**
-
-```bash
-git checkout -b feature/new-functionality
-# or with task-id: feature/IX-123-new-functionality
-```
-
-**3. Iterative development**
-
-```bash
-# Make changes...
-npm run lint        # Check linting
-npm run test        # Run tests
-git add .
-git commit -m "feat: add new functionality"
-# Hooks execute automatically
-```
-
-**4. Local testing**
-
-Test changes in a test repository:
-
-```bash
-# In test repo
-cd /path/to/test-repo
-claude-hooks install --force --skip-auth  # Reinstall from symlink
-git commit -m "test"  # Test hook
-```
-
-**5. Create PR**
-
-```bash
-git push -u origin feature/new-functionality
-claude-hooks analyze-diff main  # Generate PR metadata
-# or directly:
-claude-hooks create-pr main  # Create PR on GitHub (if MCP configured)
-```
-
-### CI/CD
-
-**Currently**: No automated CI/CD (GitHub Actions pending).
-
-**Manual verifications before merge:**
-
-1. `npm run lint` → passes
-2. `npm run test` → all tests pass
-3. Manual testing in test repo
-4. Peer code review
-5. CHANGELOG.md updated
-
-### Versioning
-
-We follow **Semantic Versioning** (MAJOR.MINOR.PATCH):
-
-- **MAJOR**: Breaking changes (e.g., 1.x → 2.0 with ES6 migration)
-- **MINOR**: New features without breaking changes (e.g., 2.2 → 2.3 with presets)
-- **PATCH**: Bug fixes (e.g., 2.6.0 → 2.6.1 with spawn ENOENT fix)
-
-**Update version:**
-
-```bash
-npm version patch  # 2.6.1 → 2.6.2
-npm version minor  # 2.6.1 → 2.7.0
-npm version major  # 2.6.1 → 3.0.0
-```
-
-**Publish to NPM:**
-
-```bash
-npm publish
-```
-
-### Conventional Commits
-
-Format: `<type>(<scope>): <subject>`
-
-**Types:**
-
-- `feat`: New functionality
-- `fix`: Bug fix
-- `docs`: Documentation only
-- `style`: Formatting (no logic change)
-- `refactor`: Refactoring without functional change
-- `test`: Add or modify tests
-- `chore`: Maintenance (deps, config)
-- `perf`: Performance improvements
-
-**Optional scopes:**
-
-- `hooks`: Changes in pre-commit or prepare-commit-msg
-- `presets`: Preset system
-- `github`: GitHub integration
-- `cli`: Main CLI commands
-- `config`: Configuration system
-- `windows`: Windows-specific fixes
-
-**Examples:**
-
-```
-feat(presets): add database preset for SQL analysis
-fix(windows): resolve spawn ENOENT with .cmd files
-docs: update CLAUDE.md with architecture details
-chore(deps): upgrade @octokit/rest to v21
-```
-
-## Release Workflow Guide
-
-This section provides a practical guide for Tech Leads and Senior developers who use the workflow automation commands. These commands are **protected** — they require `senior` or `tech-lead` role (based on GitHub repo permissions).
-
-### Quick Reference — Release Commands
-
-| Command          | When to use                 | What it does                                                             |
-| ---------------- | --------------------------- | ------------------------------------------------------------------------ |
-| `check-coupling` | Before cutting a release    | Scans open PRs for shared files — reveals which features are coupled     |
-| `create-release` | Tuesday release prep        | Creates RC branch from develop, bumps version, pushes, deploys to shadow |
-| `shadow`         | Throughout QA cycle         | Manages the shadow (QA) branch — analyze status, reset, or sync with RC  |
-| `revert-feature` | During QA, feature fails    | Finds and reverts a feature by task ID in the RC, with coupling warnings |
-| `close-release`  | QA passed, ready for deploy | Squashes RC into one commit, force-pushes, creates PR to main            |
-| `back-merge`     | After production deploy     | Tags release, resets shadow, merges main→develop, cleans up RC branch    |
-| `create-pr`      | Any PR creation             | Creates GitHub PR with auto-detected merge strategy and labels           |
-| `bump-version`   | Manual version changes      | Bumps version files, commits, tags — used outside the release cycle      |
-
-### Release Lifecycle — Step by Step
-
-The typical weekly release cycle follows this sequence:
-
-```
-1. TUESDAY — Prepare release
-   claude-hooks check-coupling              ← Are any open PRs coupled?
-   claude-hooks create-release minor        ← Create RC from develop, bump version, shadow deploy
-
-2. TUESDAY–THURSDAY — QA cycle
-   claude-hooks shadow sync release-candidate  ← Re-sync shadow after fixes
-   claude-hooks revert-feature AUT-XXXX        ← Revert a failing feature if needed
-   claude-hooks shadow analyze                 ← Check shadow divergence
-
-3. THURSDAY 12:00 — Close release
-   claude-hooks close-release "description"    ← Squash RC, create PR to main
-
-4. THURSDAY 13:00 — After deploy
-   claude-hooks back-merge                     ← Tag, reset shadow, merge main→develop, cleanup
-```
-
-### Command Details
-
-#### check-coupling
-
-Scans open PRs targeting a base branch and detects which ones share modified files (are "coupled"). Coupled features must ship together or be pulled together — reverting one may break the other.
-
-```bash
-claude-hooks check-coupling                  # PRs targeting develop (default)
-claude-hooks check-coupling --base main      # PRs targeting main
-claude-hooks check-coupling --json           # Machine-readable output for CI
-```
-
-| Flag              | Effect                                                                          |
-| ----------------- | ------------------------------------------------------------------------------- |
-| `--base <branch>` | Base branch to scan PRs against (default: `develop`)                            |
-| `--json`          | Output structured JSON with `coupledGroups`, `independentPRNumbers`, `warnings` |
-
-**Not protected** — any developer can run this. Uses GitHub API to fetch PR file lists. Transitive coupling is detected (if A shares files with B, and B with C, all three are grouped).
-
----
-
-#### create-release
-
-Creates a release-candidate branch from `develop`, bumps version files (package.json, pom.xml, etc.), commits, pushes, and deploys to shadow. Replaces 8 manual steps.
-
-```bash
-claude-hooks create-release minor            # Standard release (most common)
-claude-hooks create-release patch            # Hotfix-style bump
-claude-hooks create-release major            # Breaking change release
-```
-
-| Flag                 | Effect                                             |
-| -------------------- | -------------------------------------------------- |
-| `--dry-run`          | Preview all planned actions without making changes |
-| `--no-shadow`        | Skip shadow deployment after push                  |
-| `--skip-push`        | Keep everything local (implies no shadow)          |
-| `--update-changelog` | Generate and include CHANGELOG entry               |
-
-**Preconditions** (all checked automatically):
-
-- Must be on `develop` branch
-- Working directory must be clean
-- `develop` must be up-to-date with remote
-- `develop` must not be behind `main` (run `back-merge` first if so)
-- No existing `release-candidate/*` branch on remote (run `close-release` first)
-
-**Branch naming**: `release-candidate/V{version}` (capital V, e.g., `release-candidate/V2.31.0`).
-
----
-
-#### shadow
-
-Manages the shadow branch — an ephemeral QA environment with its own pipeline. Three subcommands:
-
-**shadow analyze** — Show divergence status:
-
-```bash
-claude-hooks shadow analyze
-```
-
-Shows how shadow compares to `main` and the active RC (commits ahead/behind). Use this to check if shadow needs a sync.
-
-**shadow reset** — Recreate shadow from main:
-
-```bash
-claude-hooks shadow reset                    # Destroys and recreates from main
-claude-hooks shadow reset --dry-run          # Preview only
-```
-
-Used at the start/end of a release cycle. Destroys the current shadow branch and creates a fresh copy from main. Prompts for confirmation.
-
-**shadow sync** — Merge a source branch into shadow:
-
-```bash
-claude-hooks shadow sync release-candidate   # Auto-detect latest RC
-claude-hooks shadow sync release-candidate/V2.31.0  # Explicit RC version
-claude-hooks shadow sync develop             # Test develop in shadow
-claude-hooks shadow sync feature/AUT-XXXX    # Test a specific feature
-claude-hooks shadow sync <source> --dry-run  # Preview only
-```
-
-| Flag        | Effect                         |
-| ----------- | ------------------------------ |
-| `--dry-run` | Preview sync without executing |
-
-**Conflict resolution during sync**: version files → accept source; CHANGELOG → keep both (warn TL); other conflicts → abort merge and advise manual resolution.
-
----
-
-#### revert-feature
-
-Finds a squash-merged feature commit by its task ID in the current release-candidate, checks for coupling with other RC features, and reverts it.
-
-```bash
-claude-hooks revert-feature AUT-3179         # Find and revert
-claude-hooks revert-feature AUT-3179 --update-shadow   # Also re-deploy shadow
-claude-hooks revert-feature AUT-3179 --dry-run         # Preview only
-```
-
-| Flag              | Effect                                             |
-| ----------------- | -------------------------------------------------- |
-| `--dry-run`       | Show what would be reverted without making changes |
-| `--update-shadow` | After reverting, sync shadow with the updated RC   |
-
-**Preconditions**: Must be on a `release-candidate/*` branch. Working directory must be clean.
-
-**Search behavior**:
-
-- 0 matches → abort with "No commits found"
-- 1 match → show details, confirm with user
-- 2+ matches → interactive menu to select which commit
-
-**Coupling detection**: Before reverting, checks if other RC commits modify the same files. Shows warnings like `"⚠️ [AUT-3200] also modifies EmailService.java"`. This is informational — you decide whether to proceed.
-
-**After revert**: Writes to `.claude/revert-log.json` for `back-merge` follow-up. Shows reminder to revert-the-revert in develop after the release deploys.
-
----
-
-#### close-release
-
-Finalizes the active release-candidate: squashes all RC commits into a single clean commit via `git reset --soft`, force-pushes, and creates a PR to main.
-
-```bash
-claude-hooks close-release                   # Auto-detect RC, prompt for description
-claude-hooks close-release "cashflow + auth" # Explicit description
-claude-hooks close-release --auto-describe   # Claude generates 1-line summary
-claude-hooks close-release --dry-run         # Preview only
-claude-hooks close-release --no-pr           # Skip PR creation
-```
-
-| Flag              | Effect                                                                      |
-| ----------------- | --------------------------------------------------------------------------- |
-| `--dry-run`       | Preview planned actions (reset, commit message, PR) without executing       |
-| `--auto-describe` | Use Claude (haiku, 60s timeout) to generate a description from feature list |
-| `--no-pr`         | Perform the reset + commit + force-push but skip GitHub PR creation         |
-
-**Description priority**: CLI argument → `--auto-describe` → interactive prompt (shows feature list, TL accepts or edits).
-
-**Commit format**:
-
-```
-Release v2.31.0: cashflow improvements + auth fixes
-
-Includes:
-- [AUT-3179] feat(cashflow): use Mailjet templates
-- [AUT-3200] fix(cashflow): handle invalid template ID
-```
-
-**PR creation**: Labels with `merge-strategy:merge-commit` and adds body reminder. This PR **must** be merged with merge-commit (not squash) to preserve history for back-merge.
-
----
-
-#### back-merge
-
-Post-deploy synchronization: tags the release on main, resets shadow, merges main into develop (with auto-conflict resolution), and cleans up the RC branch.
-
-```bash
-claude-hooks back-merge                      # Full post-deploy (main → develop)
-claude-hooks back-merge --from main --into develop   # Explicit source/destination
-claude-hooks back-merge --skip-tag           # Already tagged manually
-claude-hooks back-merge --skip-shadow        # Skip shadow reset
-claude-hooks back-merge --dry-run            # Preview only
-```
-
-| Flag              | Effect                                        |
-| ----------------- | --------------------------------------------- |
-| `--dry-run`       | Preview all planned actions without executing |
-| `--from <branch>` | Source branch (default: `main`)               |
-| `--into <branch>` | Destination branch (default: `develop`)       |
-| `--skip-tag`      | Skip tag creation (useful if already tagged)  |
-| `--skip-shadow`   | Skip shadow reset step                        |
-
-**Auto-conflict resolution**:
-| Conflict type | Resolution |
-|---|---|
-| Version files (pom.xml, package.json) | Accept source (released version) |
-| CHANGELOG.md | Keep both — destination on top, source below |
-| Other | Abort — TL resolves manually |
-
-**Revert follow-up**: If `.claude/revert-log.json` exists (from `revert-feature`), shows reverted features and offers to revert-the-revert in develop (restores them for next sprint).
-
-**Branch protection note**: `back-merge` pushes directly to `develop`. If branch protection requires PRs, you must temporarily disable it or have bypass permissions.
-
----
-
-#### create-pr (merge strategy awareness)
-
-When creating a PR, the merge strategy is auto-detected from branch naming and displayed in the preview:
-
-| PR direction                            | Strategy                          | Label                         |
-| --------------------------------------- | --------------------------------- | ----------------------------- |
-| `feature/*` → `develop`                 | Squash merge                      | `merge-strategy:squash`       |
-| `release-fix/*` → `release-candidate/*` | Squash merge                      | `merge-strategy:squash`       |
-| `release-candidate/*` → `main`          | Merge commit                      | `merge-strategy:merge-commit` |
-| `hotfix/*` → `main`                     | Merge commit                      | `merge-strategy:merge-commit` |
-| Any branch → `main`                     | Merge commit                      | `merge-strategy:merge-commit` |
-| Unknown pattern                         | Warning — user prompted to select | —                             |
-
-For merge-commit PRs, a reminder is added to the PR body: `"> ⚠️ This PR must be merged with **merge commit** (not squash)"`.
-
-### Authorization
-
-All workflow commands (except `check-coupling` and `create-pr`) are protected by role-based authorization:
-
-- **Protected commands**: `create-release`, `close-release`, `back-merge`, `shadow`, `revert-feature`, `bump-version`
-- **Role hierarchy**: `developer` < `senior` < `tech-lead`
-- **Role mapping**: GitHub repo permission `push` → developer, `maintain` → senior, `admin` → tech-lead
-- **Permissions source**: `git-hooks-config/permissions.json` repo (controlled by TL/Senior)
-- **Fail-closed**: Any auth error (no token, invalid token, network failure, repo not governed) blocks the command
-
-If blocked: `"⛔ Command 'create-release' requires role 'senior'. Your role: developer. Contact your Tech Lead."`
-
-## Useful Commands
-
-### Development
-
-```bash
-# Installation and setup
-npm install                           # Install dependencies
-npm link                              # Install globally as symlink
-npm unlink                            # Uninstall global symlink
-
-# Testing
-npm test                              # Run all tests (Jest)
-npm run test:watch                    # Tests in watch mode
-npm run test:coverage                 # Coverage report
-
-# Linting and formatting
-npm run lint                          # Check ESLint
-npm run lint:fix                      # Auto-fix ESLint issues
-npm run format                        # Format with Prettier
-
-# Versioning
-npm version patch|minor|major         # Bump version
-npm publish                           # Publish to NPM
-```
-
-### Package CLI
-
-```bash
-# Hook installation in a repo
-claude-hooks install                  # Interactive installation
-claude-hooks install --force          # Reinstall without confirmation
-claude-hooks install --skip-auth      # Skip Claude verification
-
-# Hook management
-claude-hooks status                   # View current status
-claude-hooks enable [hook]            # Enable all or specific hook
-claude-hooks disable [hook]           # Disable all or specific hook
-claude-hooks uninstall                # Completely uninstall
-
-# Presets
-claude-hooks presets                  # List available presets
-claude-hooks --set-preset backend     # Change preset
-claude-hooks preset current           # View current preset
-
-# Linting
-claude-hooks lint                     # Lint staged files
-claude-hooks lint src/                # Lint all files in directory
-claude-hooks lint src/ lib/utils/     # Multiple directories
-claude-hooks lint file1.js file2.js   # Specific files
-claude-hooks lint src/ file.js lib/   # Mix of dirs and files
-
-# Analysis and PRs
-claude-hooks analyze-diff [branch]    # Analyze diff for PR
-claude-hooks analyze-pr <pr-url>      # Analyze GitHub PR with team guidelines
-claude-hooks analyze-pr <url> --dry-run  # Analyze without posting comments
-claude-hooks check-coupling                     # Detect coupled PRs targeting develop
-claude-hooks check-coupling --base main         # Explicit base branch
-claude-hooks check-coupling --json              # Machine-readable JSON output
-claude-hooks shadow analyze                     # Show shadow divergence vs main + active RC
-claude-hooks shadow reset                       # Destroy shadow and recreate from main
-claude-hooks shadow reset --dry-run             # Preview reset without executing
-claude-hooks shadow sync release-candidate      # Merge latest RC into shadow (auto-detect)
-claude-hooks shadow sync release-candidate/V2.7.0  # Merge explicit RC into shadow
-claude-hooks shadow sync develop                # Merge develop into shadow
-claude-hooks shadow sync release-candidate --dry-run  # Preview sync without executing
-claude-hooks create-release minor                           # Create RC branch, bump, push, shadow
-claude-hooks create-release minor --no-shadow               # Skip shadow deployment
-claude-hooks create-release minor --dry-run                 # Preview only
-claude-hooks create-release minor --skip-push               # Local only (skips shadow too)
-claude-hooks create-release minor --update-changelog        # Include CHANGELOG
-claude-hooks revert-feature AUT-3179                        # Find and revert by task ID
-claude-hooks revert-feature AUT-3179 --update-shadow        # Revert and re-deploy shadow
-claude-hooks revert-feature AUT-3179 --dry-run              # Preview only
-claude-hooks close-release                                  # Auto-detect RC, prompt for description
-claude-hooks close-release "cashflow + auth"                # Explicit description
-claude-hooks close-release --auto-describe                  # Claude generates summary
-claude-hooks close-release --dry-run                        # Preview only
-claude-hooks close-release --no-pr                          # Skip PR creation
-claude-hooks create-pr [branch]       # Create PR on GitHub
-claude-hooks setup-github             # Configure GitHub token
-claude-hooks setup-linear             # Configure Linear token
-
-# Version management
-claude-hooks bump-version patch       # Bump version (commits, tags locally)
-claude-hooks bump-version minor --suffix SNAPSHOT  # With suffix
-claude-hooks bump-version major --update-changelog # With CHANGELOG
-claude-hooks bump-version patch --push             # Push tag immediately
-claude-hooks bump-version patch --no-commit        # Manual workflow
-claude-hooks bump-version patch --interactive      # Force file selection menu
-claude-hooks generate-changelog       # Generate CHANGELOG only
-
-# Help and issue reporting
-claude-hooks help "how do presets work?"  # AI-powered help (uses CLAUDE.md)
-claude-hooks help --report-issue          # Interactive issue creation
-
-# Orchestration diagnostics
-claude-hooks batch-info               # Orchestration config + per-model speed telemetry
-
-# Debugging
-claude-hooks --debug true             # Enable debug mode
-claude-hooks --debug false            # Disable debug mode
-claude-hooks --debug status           # View debug status
-
-# Auto-update
-claude-hooks update                   # Update to latest version
-```
-
-### Git with Active Hooks
-
-```bash
-# Normal commit with analysis
-git commit -m "feat: new functionality"
-
-# Commit with automatic message
-git commit -m "auto"  # Claude generates the message
-
-# Skip analysis (emergencies)
-git commit --no-verify -m "hotfix: urgent"
-
-# Amend last commit
-git commit --amend
-```
-
-### Local Testing in Test Repo
-
-```bash
-# Initial setup
-cd /path/to/test-repo
-claude-hooks install --force --skip-auth
-
-# After changes in claude-hooks
-# (npm link is already active, no need to reinstall)
-cd /path/to/test-repo
-git add test.txt
-git commit -m "test: validate changes"
-# Hooks use local version automatically
-```
-
-## Testing
-
-### Test Framework
-
-- **Framework**: Jest with ES6 modules (`--experimental-vm-modules`)
-- **Location**: `test/unit/*.test.js`
-- **Naming**: `{module-name}.test.js` matches `lib/utils/{module-name}.js`
-- **Run**: `npm test` (all), `npm run test:watch` (watch mode)
-
-### Test Patterns
-
-```javascript
-// test/unit/example.test.js
-import { functionToTest } from '../../lib/utils/example.js';
-
-describe('functionToTest', () => {
-    it('should handle normal input', () => {
-        const result = functionToTest('input');
-        expect(result).toBe('expected');
-    });
-
-    it('should throw on invalid input', () => {
-        expect(() => functionToTest(null)).toThrow('Invalid input');
-    });
-});
-```
-
-### Mocking
-
-```javascript
-// Mock child_process for git/claude commands
-import { jest } from '@jest/globals';
-import { execSync } from 'child_process';
-
-jest.mock('child_process');
-execSync.mockReturnValue('mocked output');
-```
-
-### Coverage
-
-No enforced threshold. Focus on critical paths:
-
-- `claude-client.js` - Claude CLI interaction
-- `git-operations.js` - Git command abstraction
-- `config.js` - Configuration merging
-
-## Proven Implementation Patterns
-
-Recurring patterns validated across 15+ automation sessions. Apply these in new code to avoid known pitfalls.
-
-### Testability
-
-- **`process.exit()` outside try/catch**: Mocking `process.exit` to throw requires the throw to propagate. Any surrounding `catch (e)` silently swallows it. Pattern: capture fallible values inside try/catch, check them and exit *outside* the catch block.
-- **`jest.resetAllMocks()` over `clearAllMocks()`**: `clearAllMocks()` clears call history but does NOT drain `mockResolvedValueOnce` queues. Tests that leave unconsumed values silently corrupt subsequent tests. Use `resetAllMocks()` in `beforeEach` and re-apply all defaults explicitly.
-- **`_privateHelper` export for unit testing**: Private-by-convention functions (`_` prefix) can be exported for direct unit testing without invoking the full command flow. Used in `close-release.js`, `revert-feature.js`, `shadow.js`.
-
-### Git Operations
-
-- **`execSync` with `input` for multi-line commit messages**: `git commit -F -` with `execSync({ input: fullMessage })` avoids temp files, heredocs, and `\n` escaping. Used when `createCommit()` (which only supports `-m`) is insufficient.
-- **`git diff-tree --no-commit-id -r --name-only <hash>`**: Canonical command to list files changed in a single commit. Preferable to parsing `git show --stat` (fragile) or `getChangedFilesBetweenRefs('<hash>^', '<hash>')` (breaks on first commit).
-- **`git merge --no-verify --no-ff` via `execSync`**: `mergeBranch()` in `git-operations.js` does not support `--no-verify`. For hook-free merges (shadow sync, back-merge), use `execSync` directly with the full flags.
-
-### Architecture
-
-- **`PROTECTED_COMMANDS` fast-path**: Static Set check before any API call — non-protected commands short-circuit with zero network overhead. Pattern for any guard that only applies to a subset of commands.
-- **Graceful degradation for features, fail-closed for security**: Labels, shadow sync, CHANGELOG — warn and continue on failure. Authorization, permissions — block on any error. Two fetch patterns for the same config repo.
-- **Inline Set intersection over Union-Find for single-target checks**: `coupling-detector.js` Union-Find is for N-PR transitive grouping. For checking one commit against others (revert-feature), a simple `Set` intersection per item is sufficient.
-
-## Restrictions
-
-### What Claude should NOT do in this repository
-
-1. **DO NOT add interactive prompts to git hooks**
-    - Git hooks run with stdin redirected from `/dev/null`
-    - Readline-based prompts cannot read user input in hook context
-    - Works in IDE integrations (VSCode, IntelliJ) but breaks in terminal
-    - **Solution**: Use `claude-hooks analyze` command instead (runs outside hook context)
-    - **Rationale**: Discovered through manual testing in Issue #20
-
-2. **DO NOT modify bash wrappers without corresponding Node.js changes**
-    - `templates/pre-commit` and `templates/prepare-commit-msg` are wrappers
-    - Real logic is in `lib/hooks/*.js`
-    - Changes to bash should be minimal (only Node.js invocation)
-
-3. **DO NOT use `shell: true` in `spawn()` calls**
-    - Deprecated in Node.js 24 (DEP0190)
-    - Use `which-command.js` to resolve executable paths
-    - **Exception**: Windows with `.cmd`/`.bat` requires `cmd.exe /c` wrapper
-
-4. **DO NOT modify config priority order**
-    - Maintain: defaults < user config < preset config
-    - Preset always wins (tech-stack specific has priority over user preferences)
-
-5. **DO NOT create duplicate config files**
-    - Single `.claude/config.json` per repo
-    - Presets live in `.claude/presets/{name}/`
-    - Do not create `.env` or similar files for configuration
-
-6. **DO NOT make breaking changes without MAJOR version bump**
-    - Changes in config.json structure → MAJOR
-    - Changes in CLI arguments → MAJOR
-    - Changes in template format → MINOR if backward compatible, otherwise MAJOR
-
-7. **DO NOT hardcode absolute paths**
-    - Use `getRepoRoot()` from `git-operations.js`
-    - All paths relative to repo root
-    - Exception: paths in `PATH` resolved with `which-command.js`
-
-8. **DO NOT use `console.log` directly**
-    - Always use `logger.js`: `info()`, `warning()`, `error()`, `debug()`
-    - Enables centralized output control and debug mode
-
-9. **DO NOT execute Claude CLI without timeout**
-    - Always configure timeout (default: 360s analysis, 300s commit msg)
-    - Timeout configurable in `.claude/config.json`
-
-10. **DO NOT ignore platform-specific issues**
-    - Test changes on Windows, Linux, and macOS
-    - Path separators: use `path.join()` (no hardcoded `/`)
-    - Line endings: templates use LF, convert on install if needed
-
-11. **DO NOT commit secrets**
-    - `.claude/settings.local.json` is in `.gitignore`
-    - GitHub tokens should go in settings.local or env vars
-    - Never in `.claude/config.json` (tracked)
-
-12. **DO NOT modify project `.gitignore` without consultation**
-    - `.claude/` is ignored by design (user-specific)
-    - `node_modules/` obvious
-    - New entries must be justified
-
-13. **DO NOT add dependencies without validation**
-    - Only 1 runtime dependency currently: `@octokit/rest`
-    - New deps must be justified (no built-in alternative?)
-    - Dev deps are OK if they improve DX (testing, linting)
-
-14. **DO NOT perform git operations add, commit, push unless asked to**
-    - Git flow associated with normal development must be left to human user
-
-### Technical Limitations
-
-1. **Node.js versions**: >=16.9.0 required (ES6 module features)
-2. **Claude CLI**: Must be installed and authenticated externally
-3. **Git**: Requires initialized repo (doesn't work outside git repos)
-4. **Parallel analysis**: Minimum 3 files to activate
-5. **File size**: Default max 1MB per file (configurable)
-6. **Max files**: Default 30 files per commit (configurable)
-7. **GitHub API**: Rate limits apply (5000 req/hour authenticated)
-
-### Security Considerations
-
-1. **Input sanitization**: Use `sanitize.js` for user inputs in shell commands
-2. **Token storage**: GitHub tokens in settings.local (gitignored) or env vars, NEVER tracked
-3. **Shell injection**: Avoid `shell: true`, use arrays in spawn()
-4. **Path traversal**: Validate relative paths before file operations
-5. **Secrets in diffs**: Hook should NOT prevent commits with secrets (user responsibility)
+> See [`CLAUDE-MIGRATION.md`](CLAUDE-MIGRATION.md) for a mapping of where each original CLAUDE.md section moved.