xtrm-cli 2.1.4 → 2.1.14

package/hooks/gitnexus-impact-reminder.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+import sys
+import os
+
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+from agent_context import AgentContext
+
+try:
+    ctx = AgentContext()
+    ctx.fail_open()
+except Exception as e:
+    print(f"Hook error: {e}", file=sys.stderr)
+    sys.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "2.1.4",
+  "version": "2.1.14",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",
@@ -39,5 +39,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   }
 }

package/src/commands/help.ts

@@ -8,6 +8,7 @@ declare const __dirname: string;
 
 const HOOK_CATALOG: Array<{ file: string; event: string; desc: string; beads?: true }> = [
     { file: 'main-guard.mjs',               event: 'PreToolUse',       desc: 'Blocks direct edits on protected branches' },
+    { file: 'main-guard-post-push.mjs',     event: 'PostToolUse',      desc: 'After feature-branch push, reminds PR/merge/sync steps' },
     { file: 'skill-suggestion.py',           event: 'UserPromptSubmit', desc: 'Suggests relevant skills based on user prompt' },
     { file: 'serena-workflow-reminder.py',   event: 'SessionStart',     desc: 'Injects Serena semantic editing workflow reminder' },
     { file: 'type-safety-enforcement.py',    event: 'PreToolUse',       desc: 'Prevents risky Bash and enforces safe edit patterns' },

package/src/commands/install-pi.ts

@@ -0,0 +1,117 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import prompts from 'prompts';
+import fs from 'fs-extra';
+import path from 'path';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { findRepoRoot } from '../utils/repo-root.js';
+import { t, sym } from '../utils/theme.js';
+
+const PI_AGENT_DIR = path.join(homedir(), '.pi', 'agent');
+
+interface SchemaField { key: string; label: string; hint: string; secret: boolean; required: boolean; }
+interface OAuthProvider { key: string; instruction: string; }
+interface InstallSchema { fields: SchemaField[]; oauth_providers: OAuthProvider[]; packages: string[]; }
+
+export function fillTemplate(template: string, values: Record<string, string>): string {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => values[key] ?? '');
+}
+
+
+export function readExistingPiValues(piAgentDir: string): Record<string, string> {
+    const values: Record<string, string> = {};
+    try {
+        const auth = JSON.parse(require('fs').readFileSync(path.join(piAgentDir, 'auth.json'), 'utf8'));
+        if (auth?.dashscope?.key) values['DASHSCOPE_API_KEY'] = auth.dashscope.key;
+        if (auth?.zai?.key) values['ZAI_API_KEY'] = auth.zai.key;
+    } catch { /* file doesn't exist or invalid */ }
+    try {
+        const models = JSON.parse(require('fs').readFileSync(path.join(piAgentDir, 'models.json'), 'utf8'));
+        if (!values['DASHSCOPE_API_KEY'] && models?.providers?.dashscope?.apiKey) {
+            values['DASHSCOPE_API_KEY'] = models.providers.dashscope.apiKey;
+        }
+    } catch { /* file doesn't exist or invalid */ }
+    return values;
+}
+
+function isPiInstalled(): boolean {
+    return spawnSync('pi', ['--version'], { encoding: 'utf8' }).status === 0;
+}
+
+export function createInstallPiCommand(): Command {
+    const cmd = new Command('pi');
+    cmd
+        .description('Install Pi coding agent with providers, extensions, and npm packages')
+        .option('-y, --yes', 'Skip confirmation prompts', false)
+        .action(async (opts) => {
+            const { yes } = opts;
+            const repoRoot = await findRepoRoot();
+            const piConfigDir = path.join(repoRoot, 'config', 'pi');
+
+            console.log(t.bold('\n  Pi Coding Agent Setup\n'));
+
+            if (!isPiInstalled()) {
+                console.log(kleur.yellow('  pi not found — installing oh-pi globally...\n'));
+                const r = spawnSync('npm', ['install', '-g', 'oh-pi'], { stdio: 'inherit' });
+                if (r.status !== 0) {
+                    console.error(kleur.red('\n  Failed to install oh-pi. Run: npm install -g oh-pi\n'));
+                    process.exit(1);
+                }
+                console.log(t.success('  pi installed\n'));
+            } else {
+                const v = spawnSync('pi', ['--version'], { encoding: 'utf8' });
+                console.log(t.success(`  pi ${v.stdout.trim()} already installed\n`));
+            }
+
+            const schema: InstallSchema = await fs.readJson(path.join(piConfigDir, 'install-schema.json'));
+            const existing = readExistingPiValues(PI_AGENT_DIR);
+            const values: Record<string, string> = { ...existing };
+
+            console.log(t.bold('  API Keys\n'));
+            for (const field of schema.fields) {
+                if (existing[field.key]) {
+                    console.log(t.success(`    ${sym.ok} ${field.label} [already set]`));
+                    continue;
+                }
+                if (!field.required && !yes) {
+                    const { include } = await prompts({ type: 'confirm', name: 'include', message: `  Configure ${field.label}? (optional)`, initial: false });
+                    if (!include) continue;
+                }
+                const { value } = await prompts({ type: field.secret ? 'password' : 'text', name: 'value', message: `  ${field.label}`, hint: field.hint, validate: (v) => (field.required && !v) ? 'Required' : true });
+                if (value) values[field.key] = value;
+            }
+
+            await fs.ensureDir(PI_AGENT_DIR);
+            console.log(t.muted(`\n  Writing config to ${PI_AGENT_DIR}`));
+
+            for (const name of ['models.json', 'auth.json', 'settings.json']) {
+                const destPath = path.join(PI_AGENT_DIR, name);
+                if (name === 'auth.json' && await fs.pathExists(destPath) && !yes) {
+                    const { overwrite } = await prompts({ type: 'confirm', name: 'overwrite', message: `  ${name} already exists — overwrite? (OAuth tokens will be lost)`, initial: false });
+                    if (!overwrite) { console.log(t.muted(`    skipped ${name}`)); continue; }
+                }
+                const raw = await fs.readFile(path.join(piConfigDir, `${name}.template`), 'utf8');
+                await fs.writeFile(destPath, fillTemplate(raw, values), 'utf8');
+                console.log(t.success(`    ${sym.ok} ${name}`));
+            }
+
+            await fs.copy(path.join(piConfigDir, 'extensions'), path.join(PI_AGENT_DIR, 'extensions'), { overwrite: true });
+            console.log(t.success(`    ${sym.ok} extensions/`));
+
+            console.log(t.bold('\n  npm Packages\n'));
+            for (const pkg of schema.packages) {
+                const r = spawnSync('pi', ['install', pkg], { stdio: 'inherit' });
+                if (r.status === 0) console.log(t.success(`    ${sym.ok} ${pkg}`));
+                else console.log(kleur.yellow(`    ${pkg} — failed, run manually: pi install ${pkg}`));
+            }
+
+            console.log(t.bold('\n  OAuth (manual steps)\n'));
+            for (const provider of schema.oauth_providers) {
+                console.log(t.muted(`    ${provider.key}: ${provider.instruction}`));
+            }
+
+            console.log(t.boldGreen('\n  Pi setup complete\n'));
+        });
+    return cmd;
+}

package/src/commands/install-project.ts

@@ -155,6 +155,11 @@ export function deepMergeHooks(existing: Record<string, any>, incoming: Record<s
             const incomingEventHooks = Array.isArray(incomingHooks) ? incomingHooks : [incomingHooks];
 
             const getCommand = (h: any) => h.command || h.hooks?.[0]?.command;
+            const getCommandKey = (cmd?: string): string | null => {
+                if (!cmd || typeof cmd !== 'string') return null;
+                const m = cmd.match(/([A-Za-z0-9._-]+\.(?:py|cjs|mjs|js))(?!.*[A-Za-z0-9._-]+\.(?:py|cjs|mjs|js))/);
+                return m?.[1] ?? null;
+            };
             const mergeMatcher = (existingMatcher: string, incomingMatcher: string): string => {
                 const existingParts = existingMatcher.split('|').map((s: string) => s.trim()).filter(Boolean);
                 const incomingParts = incomingMatcher.split('|').map((s: string) => s.trim()).filter(Boolean);
@@ -173,7 +178,13 @@ export function deepMergeHooks(existing: Record<string, any>, incoming: Record<s
                     continue;
                 }
 
-                const existingIndex = mergedEventHooks.findIndex((h: any) => getCommand(h) === incomingCmd);
+                const incomingKey = getCommandKey(incomingCmd);
+                const existingIndex = mergedEventHooks.findIndex((h: any) => {
+                    const existingCmd = getCommand(h);
+                    if (existingCmd === incomingCmd) return true;
+                    if (!incomingKey) return false;
+                    return getCommandKey(existingCmd) === incomingKey;
+                });
                 if (existingIndex === -1) {
                     mergedEventHooks.push(incomingHook);
                     continue;
@@ -324,8 +335,30 @@ export async function installProjectSkill(toolName: string, projectRootOverride?
     console.log(kleur.white(`  Please read: ${kleur.cyan('.claude/docs/' + toolName + '-readme.md')}\n`));
 
     if (toolName === 'tdd-guard') {
-        console.log(kleur.white('  Example for Vitest:'));
-        console.log(kleur.dim('    npm install --save-dev tdd-guard-vitest\n'));
+        // Check if tdd-guard CLI is installed globally
+        const tddGuardCheck = spawnSync('tdd-guard', ['--version'], { stdio: 'pipe' });
+        if (tddGuardCheck.status !== 0) {
+            console.log(kleur.red('  ✗ tdd-guard CLI not found globally!\n'));
+            console.log(kleur.white('  Install the global CLI:'));
+            console.log(kleur.cyan('    npm install -g tdd-guard\n'));
+        } else {
+            console.log(kleur.green('  ✓ tdd-guard CLI found globally'));
+        }
+        console.log(kleur.white('\n  Install a test reporter (choose one):'));
+        console.log(kleur.dim('    npm install --save-dev tdd-guard-vitest    # Vitest'));
+        console.log(kleur.dim('    npm install --save-dev tdd-guard-jest      # Jest'));
+        console.log(kleur.dim('    pip install tdd-guard-pytest               # pytest\n'));
+    }
+
+    if (toolName === 'quality-gates') {
+        console.log(kleur.white('  Install language dependencies:\n'));
+        console.log(kleur.white('  TypeScript:'));
+        console.log(kleur.dim('    npm install --save-dev typescript eslint prettier'));
+        console.log(kleur.white('\n  Python:'));
+        console.log(kleur.dim('    pip install ruff mypy'));
+        console.log(kleur.white('\n  For TDD (test-first) enforcement, install separately:'));
+        console.log(kleur.dim('    npm install -g tdd-guard'));
+        console.log(kleur.dim('    xtrm install project tdd-guard\n'));
     }
 
     console.log(kleur.green('  ✓ Installation complete!\n'));
@@ -354,26 +387,48 @@ export async function installAllProjectSkills(projectRootOverride?: string): Pro
 
 export function buildProjectInitGuide(): string {
     const lines = [
-        kleur.bold('\nProject Init — Recommended baseline\n'),
-        `${kleur.cyan('1) Install a quality gate skill (or equivalent checks):')}`,
-        kleur.dim('   - TypeScript projects: xtrm install project ts-quality-gate'),
-        kleur.dim('   - Python projects:     xtrm install project py-quality-gate'),
-        kleur.dim('   - TDD workflow:        xtrm install project tdd-guard'),
+        kleur.bold('\nProject Init — Production baseline\n'),
+        kleur.dim('This command prints a complete setup checklist and then bootstraps beads + GitNexus for this repo.\n'),
+        `${kleur.cyan('1) Install core project enforcement (quality-gates):')}`,
+        kleur.dim('   xtrm install project quality-gates'),
+        kleur.dim('   - Installs TypeScript + Python PostToolUse quality hooks'),
+        kleur.dim('   - Includes Serena matcher coverage for edit-equivalent tools'),
+        kleur.dim('   - Enforces linting/type-checking based on your repo config'),
         '',
-        `${kleur.cyan('2) Ensure your checks are actually configured in this repo:')}`,
-        kleur.dim('   - Testing: commands should run and fail when behavior regresses'),
-        kleur.dim('   - Linting/formatting: ESLint+Prettier (TS) or ruff (Python)'),
-        kleur.dim('   - Type checks: tsc (TS) or mypy/pyright (Python)'),
-        kleur.dim('   - Hooks only enforce what your project config defines'),
+        `${kleur.cyan('2) Optional installs depending on workflow:')}`,
+        kleur.dim('   xtrm install project tdd-guard'),
+        kleur.dim('   - Strong test-first enforcement (PreToolUse + prompt/session checks)'),
+        kleur.dim('   xtrm install project service-skills-set'),
+        kleur.dim('   - Service-aware skill routing + drift checks + git hook reminders'),
         '',
-        `${kleur.cyan('3) Optional: Service Skills Set (service-skills-set)')}`,
-        kleur.dim('   - For multi-service/Docker repos with repeated operational workflows'),
-        kleur.dim('   - Adds project hooks + skills that route Claude to service-specific context'),
-        kleur.dim('   - Helps keep architecture knowledge persistent across sessions'),
+        `${kleur.cyan('3) Configure repo checks (hooks only enforce what your repo defines):')}`,
+        kleur.dim('   - Tests: should fail on regressions (required for TDD workflows)'),
+        kleur.dim('   - TS: eslint + prettier + tsc'),
+        kleur.dim('   - PY: ruff + mypy/pyright'),
+        '',
+        `${kleur.cyan('4) Beads workflow (required for gated edit/commit flow):')}`,
+        kleur.dim('   - Claim work:   bd ready --json  ->  bd update <id> --claim --json'),
+        kleur.dim('   - During work:  keep issue status current; create discovered follow-ups'),
+        kleur.dim('   - Finish work:  bd close <id> --reason "Done" --json'),
+        '',
+        `${kleur.cyan('5) Git workflow (main-guard expected path):')}`,
+        kleur.dim('   - git checkout -b feature/<name>'),
+        kleur.dim('   - commit on feature branch only'),
+        kleur.dim('   - git push -u origin feature/<name>'),
+        kleur.dim('   - gh pr create --fill && gh pr merge --squash'),
+        kleur.dim('   - git checkout main && git pull --ff-only'),
+        '',
+        `${kleur.cyan('6) Hooks and startup automation:')}`,
+        kleur.dim('   - PreToolUse: safety gates (main/beads/TDD/type-safety/etc.)'),
+        kleur.dim('   - PostToolUse: quality checks + reminders'),
+        kleur.dim('   - Stop: beads stop-gate prevents unresolved session claims'),
+        kleur.dim('   - SessionStart: workflow context reminders'),
         '',
         kleur.bold('Quick start commands:'),
         kleur.dim('   xtrm install project list'),
-        kleur.dim('   xtrm install project ts-quality-gate   # or py-quality-gate / tdd-guard'),
+        kleur.dim('   xtrm install project quality-gates'),
+        kleur.dim('   xtrm install project tdd-guard'),
+        kleur.dim('   xtrm install project service-skills-set'),
         '',
     ];
 
@@ -382,7 +437,7 @@ export function buildProjectInitGuide(): string {
 
 async function printProjectInitGuide(): Promise<void> {
     console.log(buildProjectInitGuide());
-    await runBdInitForProject();
+    await bootstrapProjectInit();
 }
 
 async function installProjectByName(toolName: string): Promise<void> {
@@ -393,15 +448,22 @@ async function installProjectByName(toolName: string): Promise<void> {
     await installProjectSkill(toolName);
 }
 
-async function runBdInitForProject(): Promise<void> {
+async function bootstrapProjectInit(): Promise<void> {
     let projectRoot: string;
     try {
         projectRoot = getProjectRoot();
     } catch (err: any) {
-        console.log(kleur.yellow(`\n  ⚠ Skipping bd init: ${err.message}\n`));
+        console.log(kleur.yellow(`\n  ⚠ Skipping project bootstrap: ${err.message}\n`));
         return;
     }
 
+    await runBdInitForProject(projectRoot);
+    await runGitNexusInitForProject(projectRoot);
+    await syncProjectMcpServers(projectRoot);
+}
+
+async function runBdInitForProject(projectRoot: string): Promise<void> {
+
     console.log(kleur.bold('Running beads initialization (bd init)...'));
 
     const result = spawnSync('bd', ['init'], {
@@ -431,6 +493,55 @@ async function runBdInitForProject(): Promise<void> {
     if (result.stderr) process.stderr.write(result.stderr);
 }
 
+async function runGitNexusInitForProject(projectRoot: string): Promise<void> {
+    const gitnexusCheck = spawnSync('gitnexus', ['--version'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 5000,
+    });
+
+    if (gitnexusCheck.status !== 0) {
+        console.log(kleur.yellow('  ⚠ gitnexus not found; skipping index bootstrap'));
+        console.log(kleur.dim('    Install with: npm install -g gitnexus'));
+        return;
+    }
+
+    console.log(kleur.bold('Checking GitNexus index status...'));
+
+    const status = spawnSync('gitnexus', ['status'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 10000,
+    });
+
+    const statusText = `${status.stdout || ''}\n${status.stderr || ''}`.toLowerCase();
+    const needsAnalyze = status.status !== 0 ||
+        statusText.includes('stale') ||
+        statusText.includes('not indexed') ||
+        statusText.includes('missing');
+
+    if (!needsAnalyze) {
+        console.log(kleur.dim('  ✓ GitNexus index is ready'));
+        return;
+    }
+
+    console.log(kleur.bold('Running GitNexus indexing (gitnexus analyze)...'));
+    const analyze = spawnSync('gitnexus', ['analyze'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 120000,
+    });
+
+    if (analyze.status === 0) {
+        console.log(kleur.green('  ✓ GitNexus index updated'));
+        return;
+    }
+
+    if (analyze.stdout) process.stdout.write(analyze.stdout);
+    if (analyze.stderr) process.stderr.write(analyze.stderr);
+    console.log(kleur.yellow(`  ⚠ gitnexus analyze exited with code ${analyze.status}`));
+}
+
 /**
  * List available project skills.
  */
@@ -520,7 +631,7 @@ export function createInstallProjectCommand(): Command {
         });
 
     const initCmd = new Command('init')
-        .description('Show project onboarding guidance (quality gates + service skills)')
+        .description('Show full onboarding guidance and bootstrap beads + GitNexus')
         .action(async () => {
             await printProjectInitGuide();
         });
@@ -537,7 +648,7 @@ export function createProjectCommand(): Command {
 
     projectCmd
         .command('init')
-        .description('Show project onboarding guidance (quality gates + service skills)')
+        .description('Show full onboarding guidance and bootstrap beads + GitNexus')
         .action(async () => {
             await printProjectInitGuide();
         });

package/src/commands/install-service-skills.ts

@@ -60,6 +60,7 @@ const SETTINGS_HOOKS: Record<string, unknown[]> = {
 
 const MARKER_DOC = '# [jaggers] doc-reminder';
 const MARKER_STALENESS = '# [jaggers] skill-staleness';
+const MARKER_CHAIN = '# [jaggers] chain-githooks';
 
 // ─── Pure functions (exported for testing) ───────────────────────────────────
 
@@ -139,7 +140,6 @@ export async function installGitHooks(projectRoot: string, skillsSrc: string = S
     ];
 
     const hookFiles: { name: string; status: 'added' | 'already-present' }[] = [];
-    let anyAdded = false;
 
     for (const [hookPath, marker, snippet] of snippets) {
         const content = await fs.readFile(hookPath, 'utf8');
@@ -147,20 +147,47 @@ export async function installGitHooks(projectRoot: string, skillsSrc: string = S
         if (!content.includes(marker)) {
             await fs.writeFile(hookPath, content + snippet);
             hookFiles.push({ name, status: 'added' });
-            anyAdded = true;
         } else {
             hookFiles.push({ name, status: 'already-present' });
         }
     }
 
-    if (anyAdded) {
-        const gitHooksDir = path.join(projectRoot, '.git', 'hooks');
-        await fs.mkdirp(gitHooksDir);
-        for (const [src, name] of [[preCommit, 'pre-commit'], [prePush, 'pre-push']] as const) {
-            if (await fs.pathExists(src)) {
-                const dest = path.join(gitHooksDir, name);
-                await fs.copy(src, dest, { overwrite: true });
-                await fs.chmod(dest, 0o755);
+    const hooksPathResult = spawnSync('git', ['config', '--get', 'core.hooksPath'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 5000,
+    });
+    const configuredHooksPath = hooksPathResult.status === 0 ? hooksPathResult.stdout.trim() : '';
+    const activeHooksDir = configuredHooksPath
+        ? (path.isAbsolute(configuredHooksPath)
+            ? configuredHooksPath
+            : path.join(projectRoot, configuredHooksPath))
+        : path.join(projectRoot, '.git', 'hooks');
+
+    const activationTargets = new Set([path.join(projectRoot, '.git', 'hooks'), activeHooksDir]);
+    for (const hooksDir of activationTargets) {
+        await fs.mkdirp(hooksDir);
+
+        for (const [name, sourceHook] of [['pre-commit', preCommit], ['pre-push', prePush]] as const) {
+            const targetHook = path.join(hooksDir, name);
+            if (!await fs.pathExists(targetHook)) {
+                await fs.writeFile(targetHook, '#!/usr/bin/env bash\n', { mode: 0o755 });
+            } else {
+                await fs.chmod(targetHook, 0o755);
+            }
+
+            if (path.resolve(targetHook) === path.resolve(sourceHook)) {
+                continue;
+            }
+
+            const chainSnippet =
+                `\n${MARKER_CHAIN}\n` +
+                `if [ -x "${sourceHook}" ]; then\n` +
+                `    "${sourceHook}" "$@"\n` +
+                'fi\n';
+            const targetContent = await fs.readFile(targetHook, 'utf8');
+            if (!targetContent.includes(MARKER_CHAIN)) {
+                await fs.writeFile(targetHook, targetContent + chainSnippet);
             }
         }
     }

package/src/commands/install.ts

@@ -10,6 +10,7 @@ import { findRepoRoot } from '../utils/repo-root.js';
 import { t, sym } from '../utils/theme.js';
 import path from 'path';
 import { createInstallProjectCommand } from './install-project.js';
+import { createInstallPiCommand } from './install-pi.js';
 
 interface TargetChanges {
     target: string;
@@ -529,6 +530,7 @@ export function createInstallCommand(): Command {
     installCmd.addCommand(createInstallAllCommand());
     installCmd.addCommand(createInstallBasicCommand());
     installCmd.addCommand(createInstallProjectCommand());
+    installCmd.addCommand(createInstallPiCommand());
 
     return installCmd;
 }

package/src/utils/atomic-config.ts

@@ -41,6 +41,82 @@ export function isValueProtected(keyPath: string): boolean {
     );
 }
 
+function extractHookCommands(wrapper: any): string[] {
+    if (!wrapper || !Array.isArray(wrapper.hooks)) return [];
+    return wrapper.hooks
+        .map((h: any) => h?.command)
+        .filter((c: any): c is string => typeof c === 'string' && c.trim().length > 0);
+}
+
+function commandKey(command: string): string {
+    const m = command.match(/([A-Za-z0-9._-]+\.(?:py|cjs|mjs|js))(?!.*[A-Za-z0-9._-]+\.(?:py|cjs|mjs|js))/);
+    return m?.[1] || command.trim();
+}
+
+function mergeMatcher(existingMatcher: string, incomingMatcher: string): string {
+    const parts = [
+        ...existingMatcher.split('|').map((s: string) => s.trim()),
+        ...incomingMatcher.split('|').map((s: string) => s.trim()),
+    ].filter(Boolean);
+    return Array.from(new Set(parts)).join('|');
+}
+
+function mergeHookWrappers(existing: any[], incoming: any[]): any[] {
+    const merged = existing.map((w: any) => ({ ...w }));
+
+    for (const incomingWrapper of incoming) {
+        const incomingCommands = extractHookCommands(incomingWrapper);
+        if (incomingCommands.length === 0) {
+            merged.push(incomingWrapper);
+            continue;
+        }
+
+        const incomingKeys = new Set(incomingCommands.map(commandKey));
+        const existingIndex = merged.findIndex((existingWrapper: any) => {
+            const existingCommands = extractHookCommands(existingWrapper);
+            return existingCommands.some((c: string) => incomingKeys.has(commandKey(c)));
+        });
+
+        if (existingIndex === -1) {
+            merged.push(incomingWrapper);
+            continue;
+        }
+
+        const existingWrapper = merged[existingIndex];
+        if (
+            typeof existingWrapper.matcher === 'string' &&
+            typeof incomingWrapper.matcher === 'string'
+        ) {
+            existingWrapper.matcher = mergeMatcher(existingWrapper.matcher, incomingWrapper.matcher);
+        }
+
+        if (Array.isArray(existingWrapper.hooks) && Array.isArray(incomingWrapper.hooks)) {
+            const existingByKey = new Set(existingWrapper.hooks
+                .map((h: any) => h?.command)
+                .filter((c: any): c is string => typeof c === 'string')
+                .map(commandKey));
+            for (const hook of incomingWrapper.hooks) {
+                const cmd = hook?.command;
+                if (typeof cmd !== 'string' || !existingByKey.has(commandKey(cmd))) {
+                    existingWrapper.hooks.push(hook);
+                }
+            }
+        }
+    }
+
+    return merged;
+}
+
+function mergeHooksObject(existingHooks: any, incomingHooks: any): any {
+    const result = { ...(existingHooks || {}) };
+    for (const [event, incomingWrappers] of Object.entries(incomingHooks || {})) {
+        const existingWrappers = Array.isArray(result[event]) ? result[event] : [];
+        const incomingArray = Array.isArray(incomingWrappers) ? incomingWrappers : [];
+        result[event] = mergeHookWrappers(existingWrappers, incomingArray);
+    }
+    return result;
+}
+
 /**
  * Deep merge two objects, preserving protected values from the original
  */
@@ -50,6 +126,19 @@ export function deepMergeWithProtection(original: any, updates: any, currentPath
     for (const [key, value] of Object.entries(updates)) {
         const keyPath = currentPath ? `${currentPath}.${key}` : key;
 
+        // Hooks are canonical but should still preserve local custom entries.
+        // Merge by command identity and upgrade matchers for overlapping hooks.
+        if (
+            key === 'hooks' &&
+            typeof value === 'object' &&
+            value !== null &&
+            typeof original[key] === 'object' &&
+            original[key] !== null
+        ) {
+            result[key] = mergeHooksObject(original[key], value);
+            continue;
+        }
+
         // If this specific value is protected and exists locally, skip it
         if (isValueProtected(keyPath) && original.hasOwnProperty(key)) {
             continue;

package/test/atomic-config.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import { deepMergeWithProtection } from '../src/utils/atomic-config.js';
+
+describe('deepMergeWithProtection (hooks merge behavior)', () => {
+    it('upgrades matcher tokens for same hook command without duplicating hook', () => {
+        const local = {
+            hooks: {
+                PostToolUse: [{
+                    matcher: 'Write|Edit|MultiEdit',
+                    hooks: [{ command: 'python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/quality-check.py"' }],
+                }],
+            },
+        };
+
+        const incoming = {
+            hooks: {
+                PostToolUse: [{
+                    matcher: 'Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol',
+                    hooks: [{ command: 'python3 "$CLAUDE_PROJECT_DIR/hooks/quality-check.py"' }],
+                }],
+            },
+        };
+
+        const merged = deepMergeWithProtection(local, incoming);
+        const wrappers = merged.hooks.PostToolUse;
+        expect(wrappers).toHaveLength(1);
+        expect(wrappers[0].matcher).toContain('mcp__serena__insert_after_symbol');
+        expect(wrappers[0].matcher).toContain('mcp__serena__insert_before_symbol');
+        expect(wrappers[0].matcher).toContain('mcp__serena__rename_symbol');
+        expect(wrappers[0].matcher).toContain('mcp__serena__replace_symbol_body');
+        expect(wrappers[0].hooks).toHaveLength(1);
+    });
+
+    it('preserves local custom hooks and still installs incoming wrappers', () => {
+        const local = {
+            hooks: {
+                PreToolUse: [{
+                    matcher: 'Write',
+                    hooks: [{ command: 'node /custom/local-hook.mjs' }],
+                }],
+            },
+        };
+
+        const incoming = {
+            hooks: {
+                PreToolUse: [{
+                    matcher: 'Edit',
+                    hooks: [{ command: 'node /repo/hooks/main-guard.mjs' }],
+                }],
+                PostToolUse: [{
+                    matcher: 'Edit',
+                    hooks: [{ command: 'node /repo/hooks/main-guard-post-push.mjs' }],
+                }],
+            },
+        };
+
+        const merged = deepMergeWithProtection(local, incoming);
+        expect(merged.hooks.PreToolUse).toHaveLength(2);
+        expect(merged.hooks.PreToolUse[0].hooks[0].command).toBe('node /custom/local-hook.mjs');
+        expect(merged.hooks.PreToolUse[1].hooks[0].command).toBe('node /repo/hooks/main-guard.mjs');
+        expect(merged.hooks.PostToolUse).toHaveLength(1);
+    });
+
+    it('keeps protected non-hook keys unchanged', () => {
+        const local = {
+            model: 'claude-sonnet',
+            hooks: {
+                SessionStart: [{ hooks: [{ command: 'echo start-local' }] }],
+            },
+        };
+
+        const incoming = {
+            model: 'claude-opus',
+            hooks: {
+                SessionStart: [{ hooks: [{ command: 'echo start-repo' }] }],
+            },
+        };
+
+        const merged = deepMergeWithProtection(local, incoming);
+        expect(merged.model).toBe('claude-sonnet');
+        expect(merged.hooks.SessionStart).toHaveLength(2);
+    });
+});