claude-git-hooks 2.44.0 → 2.45.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.45.0] - 2026-05-13
+
+### ✨ Added
+- Added centralized config-registry module with local defaults and remote override support (SUE-138)
+- Added lib/defaults.json as the single source of truth for all package default values (SUE-138)
+
+### 🔧 Changed
+- Replaced inline hardcoded constants across modules with config-registry lookups — judge, orchestrator, Linear connector, model aliases, linter tools, and PR analysis categories now read from defaults.json with remote override capability (SUE-138)
+- Updated config merge priority to HARDCODED < remote settings.json < defaults < preset < user overrides (SUE-138)
+- Added config-registry mocks to unit tests for modules consuming centralized defaults (SUE-138)
+
+### 🐛 Fixed
+- Fixed Linear ticket fetch issue (#155)
+
+
+## [2.44.1] - 2026-05-13
+
+### ✨ Added
+- Added unit tests for linear-connector module covering ticket extraction, parsing, token loading, connection testing, and ticket fetching (SUE-154)
+
+### 🐛 Fixed
+- Fixed help command to cap book reads at 5 in Pass 2, preventing oversized prompts when the LLM requests too many library books (SUE-154)
+
+### 🗑️ Removed
+- Removed CLAUDE-MIGRATION.md — migration map no longer needed after library stabilization
+
+
 ## [2.44.0] - 2026-05-04
 
 ### ✨ Added

package/lib/commands/analyze-pr.js

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

package/lib/commands/help.js

@@ -163,6 +163,13 @@ function printAiResponse(response, source) {
 /** Package root directory — resolved once from __dirname */
 const _packageRoot = path.join(__dirname, '..', '..');
 
+/**
+ * Maximum number of books to read in Pass 2.
+ * Why: Matches the "do not request more than 5" instruction in HELP_NAVIGATE.md.
+ * Caps LLM-sourced lists to prevent oversized prompts that would fail the second call.
+ */
+const MAX_BOOKS = 5;
+
 /**
  * Catalog directories within .library/ to auto-discover
  * Why: These contain index and shelf files that form the navigational catalog.
@@ -346,6 +353,14 @@ async function readAndAnswerWithBooks(booksLine, question, catalog) {
             return null;
         }
 
+        if (bookPaths.length > MAX_BOOKS) {
+            logger.debug('help - readAndAnswerWithBooks', 'Capping book list', {
+                requested: bookPaths.length,
+                max: MAX_BOOKS
+            });
+            bookPaths.length = MAX_BOOKS;
+        }
+
         logger.debug('help - readAndAnswerWithBooks', 'Reading books from disk', { bookPaths });
 
         // Read books from local filesystem in parallel

package/lib/config.js

@@ -24,104 +24,23 @@
 import fs from 'fs';
 import path from 'path';
 import logger from './utils/logger.js';
+import { getDefaults, resolveSection } from './utils/config-registry.js';
 
 /**
- * Hardcoded defaults (v3.0.0)
- * These are NOT user-configurable - sensible defaults that work for everyone
+ * Package defaults loaded from lib/defaults.json via config-registry.
+ * These are NOT user-configurable — sensible defaults that work for everyone.
+ * See lib/defaults.json for the full structure and values.
  */
-const HARDCODED = {
-    analysis: {
-        maxFileSize: 1000000, // 1MB - sufficient for most files
-        maxFiles: 30, // Reasonable limit per commit
-        timeout: 360000, // 6 minutes - adequate for Claude API
-        contextLines: 3, // Git default
-        ignoreExtensions: [] // Can be set in advanced config only
-    },
-    commitMessage: {
-        autoKeyword: 'auto', // Standard keyword
-        timeout: 300000, // Use same timeout as analysis
-        taskIdPattern: '([A-Z]{1,3}[-\\s]\\d{3,5})' // Jira/GitHub/Linear pattern
-    },
-    subagents: {
-        enabled: true // Enable by default (faster analysis via orchestration)
-    },
-    templates: {
-        baseDir: '.claude/prompts',
-        analysis: 'CLAUDE_ANALYSIS_PROMPT.md',
-        guidelines: 'CLAUDE_PRE_COMMIT.md',
-        commitMessage: 'COMMIT_MESSAGE.md',
-        analyzeDiff: 'ANALYZE_DIFF.md',
-        resolution: 'CLAUDE_RESOLUTION_PROMPT.md',
-        createGithubPR: 'CREATE_GITHUB_PR.md'
-    },
-    output: {
-        outputDir: '.claude/out',
-        debugFile: '.claude/out/debug-claude-response.json',
-        resolutionFile: '.claude/out/claude_resolution_prompt.md',
-        prAnalysisFile: '.claude/out/pr-analysis.json'
-    },
-    system: {
-        debug: false, // Controlled by --debug flag
-        wslCheckTimeout: 15000 // System behavior
-    },
-    git: {
-        diffFilter: 'ACM' // Standard: Added, Copied, Modified
-    },
-    github: {
-        enabled: true // Always enabled
-    },
-    prAnalysis: {
-        model: 'sonnet',
-        timeout: 300000, // 5 minutes
-        inlineCategories: ['bug', 'security', 'performance', 'hotspot'],
-        generalCategories: [
-            'ticket-alignment',
-            'scope',
-            'style',
-            'good-practice',
-            'extensibility',
-            'observability',
-            'documentation',
-            'testing'
-        ]
-    },
-    linting: {
-        enabled: true, // Run linters before Claude analysis
-        autoFix: true, // Auto-fix and re-stage
-        failOnError: true, // Block commit on linting errors
-        failOnWarning: false, // Do not block on warnings
-        timeout: 30000 // 30s per linter
-    },
-    claude: {
-        defaultModel: 'sonnet' // Fallback model for SDK headless mode
-    }
-};
+const HARDCODED = getDefaults();
 
 /**
  * Default user-configurable values (v2.8.0)
+ * Derived from the github.pr section of HARDCODED.
  * Only these can be overridden in .claude/config.json
  */
 const defaults = {
-    // GitHub PR configuration (user-specific)
     github: {
-        pr: {
-            defaultBase: 'develop', // Project default branch
-            reviewers: [], // Project reviewers
-            labelRules: {
-                // Labels by preset
-                backend: ['backend', 'java'],
-                frontend: ['frontend', 'react'],
-                fullstack: ['fullstack'],
-                database: ['database', 'sql'],
-                ai: ['ai', 'tooling'],
-                default: []
-            },
-            // Auto-push configuration (v2.11.0)
-            autoPush: true, // Auto-push unpublished branches
-            pushConfirm: true, // Prompt for confirmation before push
-            verifyRemote: true, // Verify remote exists before push
-            showCommits: true // Show commit preview before push
-        }
+        pr: structuredClone(HARDCODED.github.pr)
     }
 };
 
@@ -132,7 +51,7 @@ const defaults = {
  * - v2.8.0: { version: "2.8.0", preset: "...", overrides: {...} }
  * - Legacy: { preset: "...", analysis: {...}, ... } (auto-migrates with warning)
  *
- * Merge priority: HARDCODED < defaults < preset config < user overrides
+ * Merge priority: HARDCODED < remote settings.json < defaults < preset config < user overrides
  *
  * @param {string} baseDir - Base directory to search for config (default: cwd)
  * @returns {Promise<Object>} Merged configuration
@@ -194,8 +113,17 @@ const loadUserConfig = async (baseDir = process.cwd()) => {
         }
     }
 
-    // Merge priority: HARDCODED < defaults < preset < user overrides
-    const baseConfig = deepMerge(HARDCODED, defaults);
+    // Fetch remote settings.json overrides for team-policy sections
+    const remoteSettings = {};
+    const settingsSections = ['analysis', 'commitMessage', 'linting'];
+    const sectionResults = await Promise.all(settingsSections.map((s) => resolveSection(s)));
+    settingsSections.forEach((section, i) => {
+        if (sectionResults[i]) remoteSettings[section] = sectionResults[i];
+    });
+
+    // Merge priority: HARDCODED < remote settings.json < defaults < preset < user overrides
+    const withRemote = deepMerge(HARDCODED, remoteSettings);
+    const baseConfig = deepMerge(withRemote, defaults);
     const withPreset = deepMerge(baseConfig, presetConfig);
     const final = deepMerge(withPreset, userOverrides);
 

package/lib/defaults.json

@@ -0,0 +1,130 @@
+{
+    "analysis": {
+        "maxFileSize": 1000000,
+        "maxFiles": 30,
+        "timeout": 360000,
+        "contextLines": 3,
+        "ignoreExtensions": []
+    },
+    "commitMessage": {
+        "autoKeyword": "auto",
+        "timeout": 300000,
+        "taskIdPattern": "([A-Z]{1,3}[-\\s]\\d{3,5})"
+    },
+    "subagents": {
+        "enabled": true
+    },
+    "templates": {
+        "baseDir": ".claude/prompts",
+        "analysis": "CLAUDE_ANALYSIS_PROMPT.md",
+        "guidelines": "CLAUDE_PRE_COMMIT.md",
+        "commitMessage": "COMMIT_MESSAGE.md",
+        "analyzeDiff": "ANALYZE_DIFF.md",
+        "resolution": "CLAUDE_RESOLUTION_PROMPT.md",
+        "createGithubPR": "CREATE_GITHUB_PR.md"
+    },
+    "output": {
+        "outputDir": ".claude/out",
+        "debugFile": ".claude/out/debug-claude-response.json",
+        "resolutionFile": ".claude/out/claude_resolution_prompt.md",
+        "prAnalysisFile": ".claude/out/pr-analysis.json"
+    },
+    "system": {
+        "debug": false,
+        "wslCheckTimeout": 15000
+    },
+    "git": {
+        "diffFilter": "ACM"
+    },
+    "github": {
+        "enabled": true,
+        "pr": {
+            "defaultBase": "develop",
+            "reviewers": [],
+            "labelRules": {
+                "backend": ["backend", "java"],
+                "frontend": ["frontend", "react"],
+                "fullstack": ["fullstack"],
+                "database": ["database", "sql"],
+                "ai": ["ai", "tooling"],
+                "default": []
+            },
+            "autoPush": true,
+            "pushConfirm": true,
+            "verifyRemote": true,
+            "showCommits": true
+        }
+    },
+    "prAnalysis": {
+        "model": "sonnet",
+        "timeout": 300000,
+        "inlineCategories": ["bug", "security", "performance", "hotspot"],
+        "generalCategories": [
+            "ticket-alignment",
+            "scope",
+            "style",
+            "good-practice",
+            "extensibility",
+            "observability",
+            "documentation",
+            "testing"
+        ]
+    },
+    "linting": {
+        "enabled": true,
+        "autoFix": true,
+        "failOnError": true,
+        "failOnWarning": false,
+        "timeout": 30000
+    },
+    "claude": {
+        "defaultModel": "sonnet"
+    },
+    "models": {
+        "modelMap": {
+            "haiku": "claude-haiku-4-5-20251001",
+            "sonnet": "claude-sonnet-4-6",
+            "opus": "claude-opus-4-6"
+        },
+        "defaults": {
+            "analysis": "sonnet",
+            "orchestrator": "opus",
+            "judge": "sonnet",
+            "prAnalysis": "sonnet",
+            "commitMessage": "sonnet"
+        }
+    },
+    "tools": {
+        "prettier": { "enabled": true, "timeout": 30000 },
+        "eslint": { "enabled": true, "timeout": 30000 },
+        "spotless": { "enabled": true, "timeout": 120000, "perFile": true },
+        "sqlfluff": { "enabled": true, "timeout": 30000 }
+    },
+    "presetLinters": {
+        "frontend": ["prettier", "eslint"],
+        "backend": ["spotless"],
+        "fullstack": ["prettier", "eslint", "spotless"],
+        "database": ["sqlfluff"],
+        "ai": ["prettier", "eslint"],
+        "default": ["prettier", "eslint"]
+    },
+    "judge": {
+        "model": "sonnet",
+        "timeout": 360000
+    },
+    "orchestrator": {
+        "model": "opus",
+        "timeout": 60000,
+        "threshold": 3
+    },
+    "prMetadata": {
+        "timeout": 180000,
+        "maxDiffSize": 50000
+    },
+    "linear": {
+        "hostname": "api.linear.app",
+        "path": "/graphql",
+        "timeout": 10000,
+        "maxRetries": 2
+    }
+}

package/lib/utils/analysis-engine.js

@@ -35,6 +35,7 @@ import { orchestrateBatches } from './diff-analysis-orchestrator.js';
 import { buildAnalysisPrompt } from './prompt-builder.js';
 import logger from './logger.js';
 import { recordMetric } from './metrics.js';
+import { getDefaultSection, resolveSection } from './config-registry.js';
 
 /**
  * Standard file data schema used throughout the analysis pipeline
@@ -360,7 +361,7 @@ export const displayResults = (result, { silent = false } = {}) => {
 };
 
 // Minimum file count to trigger Opus orchestration instead of sequential analysis
-const ORCHESTRATOR_THRESHOLD = 3;
+const ORCHESTRATOR_THRESHOLD = getDefaultSection('orchestrator').threshold;
 
 /**
  * Runs code analysis on files
@@ -385,12 +386,15 @@ export const runAnalysis = async (filesData, config, options = {}) => {
         return createEmptyResult();
     }
 
-    const useOrchestrator = filesData.length >= ORCHESTRATOR_THRESHOLD;
+    // Resolve orchestrator threshold: remote settings.json > local defaults.json
+    const orchConfig = await resolveSection('orchestrator');
+    const threshold = orchConfig?.threshold || ORCHESTRATOR_THRESHOLD;
+    const useOrchestrator = filesData.length >= threshold;
 
     logger.debug('analysis-engine - runAnalysis', 'Starting analysis', {
         fileCount: filesData.length,
         useOrchestrator,
-        threshold: ORCHESTRATOR_THRESHOLD
+        threshold
     });
 
     let result;

package/lib/utils/claude-client.js

@@ -21,6 +21,7 @@ import path from 'path';
 import os from 'os';
 import logger from './logger.js';
 import config from '../config.js';
+import { getDefaultSection } from './config-registry.js';
 import {
     detectClaudeError,
     formatClaudeError,
@@ -47,14 +48,17 @@ class ClaudeClientError extends Error {
 
 /**
  * Model alias map — resolves shorthand names to full SDK model IDs.
+ * Loaded from lib/defaults.json via config-registry, with env var overrides.
  * Env var overrides match Lumiere contract (CLAUDE_MODEL_HAIKU, CLAUDE_MODEL_SONNET, CLAUDE_MODEL_OPUS).
  * Full model IDs (e.g., 'claude-sonnet-4-6') pass through unchanged.
  */
-const MODEL_ALIASES = {
-    haiku: process.env.CLAUDE_MODEL_HAIKU || 'claude-haiku-4-5-20251001',
-    sonnet: process.env.CLAUDE_MODEL_SONNET || 'claude-sonnet-4-6',
-    opus: process.env.CLAUDE_MODEL_OPUS || 'claude-opus-4-6'
-};
+const _localModelMap = getDefaultSection('models').modelMap;
+const MODEL_ALIASES = Object.fromEntries(
+    Object.entries(_localModelMap).map(([alias, fullId]) => [
+        alias,
+        process.env[`CLAUDE_MODEL_${alias.toUpperCase()}`] || fullId
+    ])
+);
 
 /**
  * Resolves a model alias to a full model ID.

package/lib/utils/config-registry.js

@@ -0,0 +1,257 @@
+/**
+ * File: config-registry.js
+ * Purpose: Unified configuration reader with local defaults + remote overrides
+ *
+ * Design:
+ * - Reads lib/defaults.json synchronously at import time (ships with the package)
+ * - Fetches remote overrides from git-hooks-config via remote-config.js (async, cached)
+ * - Merge priority: local defaults < remote overrides
+ * - Consumers higher in the chain (presets, user .claude/config.json) merge on top separately
+ *
+ * Section-to-remote-file mapping:
+ *   models       → models.json       (root)
+ *   tools        → tools.json        (.tools key)
+ *   prAnalysis   → categories.json   (.inlineCategories, .generalCategories → merged into prAnalysis)
+ *   presetLinters → formatters.json  (.presetTools)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import logger from './logger.js';
+import { fetchRemoteConfig } from './remote-config.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Path to the package defaults file */
+const DEFAULTS_PATH = path.resolve(__dirname, '..', 'defaults.json');
+
+/**
+ * Helper: create a mapping entry that reads a section key from settings.json.
+ * @param {string} sectionKey - Key within settings.json (e.g., 'analysis', 'judge')
+ * @returns {{ file: string, extract: (remote: Object) => Object }}
+ */
+const _settingsEntry = (sectionKey) => ({
+    file: 'settings.json',
+    extract: (remote) => remote?.[sectionKey] || {}
+});
+
+/**
+ * Maps defaults.json section names to remote config files and their extraction logic.
+ * Each entry defines:
+ * - file: the remote JSON filename to fetch
+ * - extract: function that transforms the remote JSON into the shape expected for deep-merge
+ * @type {Object<string, { file: string, extract: (remote: Object) => Object }>}
+ */
+const SECTION_REMOTE_MAP = {
+    models: {
+        file: 'models.json',
+        extract: (remote) => remote
+    },
+    tools: {
+        file: 'tools.json',
+        extract: (remote) => remote?.tools || {}
+    },
+    prAnalysis: {
+        file: 'categories.json',
+        extract: (remote) => {
+            const result = {};
+            if (remote?.inlineCategories) result.inlineCategories = remote.inlineCategories;
+            if (remote?.generalCategories) result.generalCategories = remote.generalCategories;
+            return result;
+        }
+    },
+    presetLinters: {
+        file: 'formatters.json',
+        extract: (remote) => remote?.presetTools || {}
+    },
+    // Team-policy sections — all read from settings.json
+    analysis: _settingsEntry('analysis'),
+    commitMessage: _settingsEntry('commitMessage'),
+    judge: _settingsEntry('judge'),
+    orchestrator: _settingsEntry('orchestrator'),
+    prMetadata: _settingsEntry('prMetadata'),
+    linting: _settingsEntry('linting')
+};
+
+// ── Sync: local defaults (read once at import time) ────────────────────────
+
+let _defaults = null;
+
+/**
+ * Load defaults.json synchronously. Called once at module init.
+ * @returns {Object} Parsed defaults
+ * @throws {Error} If defaults.json is missing or invalid (fatal — package is broken)
+ */
+function _loadDefaults() {
+    if (_defaults !== null) return _defaults;
+
+    try {
+        const raw = fs.readFileSync(DEFAULTS_PATH, 'utf8');
+        _defaults = JSON.parse(raw);
+        logger.debug('config-registry', 'Loaded defaults.json', {
+            sections: Object.keys(_defaults)
+        });
+        return _defaults;
+    } catch (err) {
+        throw new Error(
+            `Failed to load package defaults from ${DEFAULTS_PATH}: ${err.message}. ` +
+                'This indicates a broken installation — reinstall claude-git-hooks.'
+        );
+    }
+}
+
+// Load immediately on import
+_loadDefaults();
+
+/**
+ * Returns the full defaults object (sync, no I/O after init).
+ * @returns {Object} Complete defaults from lib/defaults.json
+ */
+export function getDefaults() {
+    return _defaults;
+}
+
+/**
+ * Returns a single section from defaults (sync).
+ * @param {string} sectionName - Top-level key in defaults.json (e.g., 'models', 'tools', 'judge')
+ * @returns {Object|undefined} The section value, or undefined if not found
+ */
+export function getDefaultSection(sectionName) {
+    return _defaults?.[sectionName];
+}
+
+// ── Async: remote overrides (fetched on demand, cached) ────────────────────
+
+/**
+ * In-memory cache for resolved sections (local + remote merged).
+ * @type {Map<string, Object>}
+ */
+const _resolvedCache = new Map();
+
+/**
+ * Deep-merge two objects (source overrides target).
+ * Arrays are replaced wholesale (not concatenated).
+ * @param {Object} target - Base object
+ * @param {Object} source - Override object
+ * @returns {Object} Merged result
+ */
+function _deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+            result[key] = _deepMerge(target[key] || {}, source[key]);
+        } else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+
+/**
+ * Resolve a config section by merging local defaults with remote overrides.
+ *
+ * If the section has a mapping in SECTION_REMOTE_MAP, the corresponding remote
+ * file is fetched and merged (remote > local). If fetch fails, local defaults
+ * are returned. Results are cached per process.
+ *
+ * @param {string} sectionName - Top-level key in defaults.json
+ * @returns {Promise<Object>} Merged section (local defaults + remote overrides)
+ */
+export async function resolveSection(sectionName) {
+    if (_resolvedCache.has(sectionName)) {
+        return _resolvedCache.get(sectionName);
+    }
+
+    const localSection = getDefaultSection(sectionName);
+    if (localSection === undefined) {
+        logger.debug('config-registry - resolveSection', 'Section not found in defaults', {
+            sectionName
+        });
+        return undefined;
+    }
+
+    const mapping = SECTION_REMOTE_MAP[sectionName];
+    if (!mapping) {
+        // No remote file for this section — return local as-is
+        _resolvedCache.set(sectionName, localSection);
+        return localSection;
+    }
+
+    const remoteData = await fetchRemoteConfig(mapping.file);
+    if (!remoteData) {
+        logger.debug('config-registry - resolveSection', 'Remote unavailable, using local defaults', {
+            sectionName,
+            remoteFile: mapping.file
+        });
+        _resolvedCache.set(sectionName, localSection);
+        return localSection;
+    }
+
+    const remoteOverrides = mapping.extract(remoteData);
+    const merged = _deepMerge(localSection, remoteOverrides);
+
+    logger.debug('config-registry - resolveSection', 'Merged local + remote', {
+        sectionName,
+        remoteFile: mapping.file,
+        localKeys: Object.keys(localSection),
+        remoteKeys: Object.keys(remoteOverrides)
+    });
+
+    _resolvedCache.set(sectionName, merged);
+    return merged;
+}
+
+// ── Convenience resolvers ──────────────────────────────────────────────────
+
+/**
+ * Resolve a model alias to a full model ID, with remote override support.
+ * Priority: env var > remote models.json > local defaults.json
+ *
+ * @param {string} alias - Model alias ('sonnet', 'opus', 'haiku') or full ID
+ * @returns {Promise<string>} Full model ID
+ */
+export async function resolveModelAlias(alias) {
+    const modelsConfig = await resolveSection('models');
+    const modelMap = modelsConfig?.modelMap || {};
+
+    // Env var override (highest priority)
+    const envKey = `CLAUDE_MODEL_${alias.toUpperCase()}`;
+    if (process.env[envKey]) {
+        return process.env[envKey];
+    }
+
+    return modelMap[alias] || alias;
+}
+
+/**
+ * Resolve configuration for a specific linter tool, with remote override support.
+ * Merges local defaults.tools[toolName] with remote tools.json tools[toolName].
+ *
+ * @param {string} toolName - Tool name ('prettier', 'eslint', 'spotless', 'sqlfluff')
+ * @returns {Promise<Object|undefined>} Tool config (enabled, timeout, perFile) or undefined
+ */
+export async function resolveToolConfig(toolName) {
+    const toolsConfig = await resolveSection('tools');
+    return toolsConfig?.[toolName];
+}
+
+// ── Test helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Reset all caches. Test helper — not intended for production use.
+ */
+export function _resetRegistry() {
+    _resolvedCache.clear();
+    _defaults = null;
+    _loadDefaults();
+}
+
+/**
+ * Reset resolved cache only (keeps defaults loaded).
+ * Useful for testing remote merge behavior without re-reading defaults.json.
+ */
+export function _resetResolvedCache() {
+    _resolvedCache.clear();
+}

package/lib/utils/diff-analysis-orchestrator.js

@@ -23,10 +23,11 @@ import path from 'path';
 import { executeClaudeWithRetry, extractJSON } from './claude-client.js';
 import { loadPrompt } from './prompt-builder.js';
 import logger from './logger.js';
+import { getDefaultSection, resolveSection } from './config-registry.js';
 
-// Orchestration model — Opus for semantic grouping quality, not user-configurable
-const ORCHESTRATOR_MODEL = 'opus';
-const ORCHESTRATOR_TIMEOUT = 60000; // 60s — lightweight call, just file overview
+// Orchestration config from lib/defaults.json (sync fallback)
+const { model: ORCHESTRATOR_MODEL, timeout: ORCHESTRATOR_TIMEOUT } =
+    getDefaultSection('orchestrator');
 
 /**
  * Counts added/removed lines in a unified diff string
@@ -184,6 +185,10 @@ const _buildCommonContext = (filesData, batchGroups) => {
  * @returns {Promise<{batches: Array<{files: FileData[], rationale: string, model: string}>, commonContext: string}>}
  */
 export const orchestrateBatches = async (filesData, { headless = false } = {}) => {
+    // Resolve orchestrator config: remote settings.json > local defaults.json
+    const orchConfig = await resolveSection('orchestrator');
+    const orchModel = orchConfig?.model || ORCHESTRATOR_MODEL;
+    const orchTimeout = orchConfig?.timeout || ORCHESTRATOR_TIMEOUT;
     logger.debug('diff-analysis-orchestrator - orchestrateBatches', 'Building file overview', {
         fileCount: filesData.length
     });
@@ -214,20 +219,20 @@ export const orchestrateBatches = async (filesData, { headless = false } = {}) =
     }
 
     logger.debug('diff-analysis-orchestrator - orchestrateBatches', 'Calling Opus orchestrator', {
-        model: ORCHESTRATOR_MODEL,
-        timeout: ORCHESTRATOR_TIMEOUT
+        model: orchModel,
+        timeout: orchTimeout
     });
 
     let rawResponse;
     try {
         rawResponse = await executeClaudeWithRetry(prompt, {
-            model: ORCHESTRATOR_MODEL,
-            timeout: ORCHESTRATOR_TIMEOUT,
+            model: orchModel,
+            timeout: orchTimeout,
             headless,
             telemetryContext: {
                 hook: 'orchestrator',
                 fileCount: filesData.length,
-                model: ORCHESTRATOR_MODEL
+                model: orchModel
             }
         });
     } catch (err) {

package/lib/utils/judge.js

@@ -26,9 +26,9 @@ import { formatBlockingIssues, getAffectedFiles, formatFileContents } from './re
 import { getRepoRoot, getRepoName, getCurrentBranch } from './git-operations.js';
 import logger from './logger.js';
 import { recordMetric } from './metrics.js';
+import { getDefaultSection, resolveSection } from './config-registry.js';
 
-const JUDGE_DEFAULT_MODEL = 'sonnet';
-const JUDGE_TIMEOUT = 360000;
+const { model: JUDGE_DEFAULT_MODEL, timeout: JUDGE_TIMEOUT } = getDefaultSection('judge');
 
 /**
  * Applies a single search/replace fix to a file and stages it
@@ -103,7 +103,10 @@ const applyFix = async (fix, repoRoot) => {
  * @returns {Promise<{fixedCount: number, falsePositiveCount: number, remainingIssues: Array, verdicts: Array}>}
  */
 const judgeAndFix = async (analysisResult, filesData, config, { headless = false } = {}) => {
-    const model = config.judge?.model || JUDGE_DEFAULT_MODEL;
+    // Resolve judge config: remote settings.json > local defaults.json
+    const judgeConfig = await resolveSection('judge');
+    const model = config.judge?.model ?? judgeConfig?.model ?? JUDGE_DEFAULT_MODEL;
+    const judgeTimeout = judgeConfig?.timeout ?? JUDGE_TIMEOUT;
     const repoRoot = getRepoRoot();
 
     // Get all issues: prefer details (all severities), fallback to blockingIssues
@@ -135,7 +138,7 @@ const judgeAndFix = async (analysisResult, filesData, config, { headless = false
     // Call LLM
     const response = await executeClaudeWithRetry(prompt, {
         model,
-        timeout: JUDGE_TIMEOUT,
+        timeout: judgeTimeout,
         headless
     });
 

package/lib/utils/linear-connector.js

@@ -19,11 +19,13 @@
 import https from 'https';
 import logger from './logger.js';
 import { loadToken } from './token-store.js';
+import { getDefaultSection } from './config-registry.js';
 
-const LINEAR_HOSTNAME = 'api.linear.app';
-const LINEAR_PATH = '/graphql';
-const LINEAR_TIMEOUT = 10000;
-const MAX_RETRIES = 2;
+const linearDefaults = getDefaultSection('linear') || {};
+const LINEAR_HOSTNAME = linearDefaults.hostname || 'api.linear.app';
+const LINEAR_PATH = linearDefaults.path || '/graphql';
+const LINEAR_TIMEOUT = linearDefaults.timeout || 10000;
+const MAX_RETRIES = linearDefaults.maxRetries || 2;
 
 /**
  * Custom error for Linear connector failures

package/lib/utils/linter-runner.js

@@ -27,6 +27,7 @@ import {
 import { getRepoRoot } from './git-operations.js';
 import { which } from './which-command.js';
 import { fetchRemoteConfig } from './remote-config.js';
+import { resolveSection } from './config-registry.js';
 import logger from './logger.js';
 
 /**
@@ -422,6 +423,9 @@ export async function runLinters(files, config, presetName = 'default') {
     const timeout = lintConfig.timeout || 30000;
 
     const tools = await getLinterToolsForPreset(presetName);
+
+    // Merge remote tools.json overrides (timeout, perFile, enabled) into tool definitions
+    const remoteToolsConfig = await resolveSection('tools');
     const results = [];
 
     logger.debug('linter-runner - runLinters', 'Starting linters', {
@@ -431,7 +435,18 @@ export async function runLinters(files, config, presetName = 'default') {
         autoFix
     });
 
-    for (const toolDef of tools) {
+    for (let toolDef of tools) {
+        // Apply remote tool config overrides (remote > local)
+        const remoteToolOverride = remoteToolsConfig?.[toolDef.name];
+        if (remoteToolOverride) {
+            toolDef = { ...toolDef };
+            if (remoteToolOverride.timeout !== undefined) toolDef.timeout = remoteToolOverride.timeout;
+            if (remoteToolOverride.perFile !== undefined) toolDef.perFile = remoteToolOverride.perFile;
+            if (remoteToolOverride.enabled === false) {
+                logger.info(`Skipping ${toolDef.name} (disabled by remote config)`);
+                continue;
+            }
+        }
         // Filter files by tool's extensions
         const matchingFiles = filterFilesByTool(files, toolDef);
 

package/lib/utils/pr-metadata-engine.js

@@ -32,6 +32,7 @@ import { executeClaudeWithRetry, extractJSON } from './claude-client.js';
 import { loadPrompt } from './prompt-builder.js';
 import { getConfig } from '../config.js';
 import logger from './logger.js';
+import { getDefaultSection, resolveSection } from './config-registry.js';
 
 /**
  * @typedef {Object} BranchContext
@@ -58,13 +59,11 @@ import logger from './logger.js';
  */
 
 /**
- * Internal defaults (not documented in config.example.json)
+ * Internal defaults loaded from lib/defaults.json
  * Why: Convention over configuration - sensible defaults for 95% of cases
+ * Fallbacks: timeout=180000 (3 min), maxDiffSize=51200 (50KB)
  */
-const DEFAULTS = {
-    timeout: 180000, // 3 minutes
-    maxDiffSize: 50000 // 50KB
-};
+const DEFAULTS = getDefaultSection('prMetadata') || { timeout: 180000, maxDiffSize: 50000 };
 
 /**
  * Builds diff payload with tiered reduction strategy
@@ -310,12 +309,14 @@ export const getBranchContext = async (targetBranch) => {
 
         logger.debug('pr-metadata-engine - getBranchContext', 'Commits retrieved');
 
-        // Build diff payload with tiered reduction
+        // Build diff payload with tiered reduction (remote settings.json > local defaults)
+        const resolvedPrMeta = await resolveSection('prMetadata');
+        const maxDiffSize = resolvedPrMeta?.maxDiffSize || DEFAULTS.maxDiffSize;
         const {
             payload: diff,
             isTruncated,
             truncationDetails
-        } = buildDiffPayload(baseBranch, 'HEAD', files, DEFAULTS.maxDiffSize);
+        } = buildDiffPayload(baseBranch, 'HEAD', files, maxDiffSize);
 
         logger.debug('pr-metadata-engine - getBranchContext', 'Diff payload built', {
             diffSize: diff.length,
@@ -371,7 +372,9 @@ export const getBranchContext = async (targetBranch) => {
 export const generatePRMetadata = async (context, options = {}) => {
     const config = await getConfig();
     const configTimeout = config.analysis?.timeout;
-    const { timeout = configTimeout || DEFAULTS.timeout, hook = 'pr-metadata', headless = false, costTracker = null } = options;
+    const resolvedPrMetaGen = await resolveSection('prMetadata');
+    const defaultTimeout = resolvedPrMetaGen?.timeout || DEFAULTS.timeout;
+    const { timeout = configTimeout || defaultTimeout, hook = 'pr-metadata', headless = false, costTracker = null } = options;
 
     logger.debug('pr-metadata-engine - generatePRMetadata', 'Generating PR metadata', {
         filesCount: context.filesCount,

package/package.json

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